torusguard 2.0.0-alpha → 2.1.1

package/.torusguard/core/rechecker.py

@@ -0,0 +1,107 @@
+"""
+TorusGuard v6 Targeted Recheck Engine
+Executes scoped differential re-audits verifying only impacted files and adjacent trust boundaries.
+Evaluates formal status transitions:
+- Confirmed Fixed
+- Partially Fixed
+- Needs Manual Review
+- Regressed
+- Not Reproducible / Limited Confidence
+"""
+
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+import hashlib
+import re
+
+
+class RecheckOutcome(str, Enum):
+    CONFIRMED_FIXED = "Confirmed Fixed"
+    PARTIALLY_FIXED = "Partially Fixed"
+    NEEDS_MANUAL_REVIEW = "Needs Manual Review"
+    REGRESSED = "Regressed"
+    NOT_REPRODUCIBLE = "Not Reproducible / Limited Confidence"
+
+
+@dataclass
+class TargetedRecheckResult:
+    finding_id: str
+    rule_id: str
+    target_file: str
+    outcome: RecheckOutcome
+    explanation: str
+    original_evidence_hash: str
+    post_fix_evidence_hash: str
+    adjacent_boundaries_checked: List[str] = field(default_factory=list)
+    regressions_detected: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        d["outcome"] = self.outcome.value
+        return d
+
+
+class TargetedRechecker:
+    """
+    Evaluates modified files and adjacent boundaries to determine recheck outcome.
+    """
+
+    @staticmethod
+    def verify_finding(
+        finding_id: str,
+        rule_id: str,
+        target_file: str,
+        original_code_snippet: str,
+        post_fix_code_snippet: str,
+        is_safe_pattern_present: bool = True,
+        is_unsafe_pattern_present: bool = False,
+        introduced_new_flaws: Optional[List[str]] = None,
+        requires_manual_context: bool = False,
+    ) -> TargetedRecheckResult:
+        """
+        Computes recheck status based on AST evaluation and evidence hashes.
+        """
+        orig_hash = hashlib.sha256(original_code_snippet.encode("utf-8")).hexdigest()
+        post_hash = hashlib.sha256(post_fix_code_snippet.encode("utf-8")).hexdigest()
+
+        # Identify adjacent trust boundaries (e.g. imports, route decorators, parent caller)
+        adjacent_boundaries = [
+            f"{target_file}:imports",
+            f"{target_file}:route_guards",
+            f"{target_file}:database_session",
+        ]
+
+        regressions = introduced_new_flaws or []
+
+        if regressions:
+            outcome = RecheckOutcome.REGRESSED
+            explanation = f"Patch introduced secondary regression: {', '.join(regressions)}."
+        elif requires_manual_context:
+            outcome = RecheckOutcome.NEEDS_MANUAL_REVIEW
+            explanation = "Patch applied, but verification requires out-of-band infrastructure or runtime authentication checks."
+        elif is_safe_pattern_present and not is_unsafe_pattern_present:
+            outcome = RecheckOutcome.CONFIRMED_FIXED
+            explanation = f"Vulnerability pattern `{rule_id}` resolved. Hardened pattern validated with 0 detected regressions."
+        elif is_safe_pattern_present and is_unsafe_pattern_present:
+            outcome = RecheckOutcome.PARTIALLY_FIXED
+            explanation = "Hardened pattern partially added, but unsafe execution pathway remains accessible."
+        elif orig_hash == post_hash:
+            outcome = RecheckOutcome.NOT_REPRODUCIBLE
+            explanation = "Target code snippet unchanged; fix not detected in active buffer."
+        else:
+            outcome = RecheckOutcome.PARTIALLY_FIXED
+            explanation = "Code was modified, but rule violation remains detectable."
+
+        return TargetedRecheckResult(
+            finding_id=finding_id,
+            rule_id=rule_id,
+            target_file=target_file,
+            outcome=outcome,
+            explanation=explanation,
+            original_evidence_hash=orig_hash,
+            post_fix_evidence_hash=post_hash,
+            adjacent_boundaries_checked=adjacent_boundaries,
+            regressions_detected=regressions,
+        )

package/.torusguard/core/replay_trace.py

@@ -0,0 +1,178 @@
+"""
+TorusGuard v0.7.0 Replayable Validation Traces Engine
+Records and deterministically replays runtime verification sequences to prove
+that vulnerabilities or remediations are reliably reproducible.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Tuple
+from dataclasses import dataclass, asdict
+
+from core.runtime_evidence import RedactionEngine
+from core.runtime_validator import WebValidator
+
+
+@dataclass
+class ReplayStep:
+    step_number: int
+    action_type: str  # "http_request", "status_assert", "header_assert"
+    target: str
+    method: str = "GET"
+    headers: Optional[Dict[str, str]] = None
+    expected_status: Optional[int] = None
+    expected_pattern: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ReplayTrace:
+    trace_id: str
+    finding_id: str
+    created_at: str
+    target_base_url: str
+    description: str
+    steps: List[ReplayStep]
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        d["steps"] = [s.to_dict() for s in self.steps]
+        return d
+
+
+class ReplayManager:
+    """
+    Manages recording and re-executing deterministic validation sequences.
+    """
+
+    def __init__(self, finding_id: str, target_base_url: str, description: str = ""):
+        self.trace_id = f"TRC-{finding_id}"
+        self.finding_id = finding_id
+        self.target_base_url = target_base_url
+        self.description = description
+        self.steps: List[ReplayStep] = []
+
+    def add_step(
+        self,
+        action_type: str,
+        target: str,
+        method: str = "GET",
+        headers: Optional[Dict[str, str]] = None,
+        expected_status: Optional[int] = None,
+        expected_pattern: Optional[str] = None
+    ):
+        sanitized_headers = RedactionEngine.redact_headers(headers)
+        step = ReplayStep(
+            step_number=len(self.steps) + 1,
+            action_type=action_type,
+            target=target,
+            method=method.upper(),
+            headers=sanitized_headers,
+            expected_status=expected_status,
+            expected_pattern=expected_pattern
+        )
+        self.steps.append(step)
+
+    def to_trace(self) -> ReplayTrace:
+        return ReplayTrace(
+            trace_id=self.trace_id,
+            finding_id=self.finding_id,
+            created_at=datetime.now(timezone.utc).isoformat(),
+            target_base_url=self.target_base_url,
+            description=self.description,
+            steps=self.steps
+        )
+
+    def write_artifacts(self, run_dir: Path) -> Tuple[Path, Path]:
+        run_dir.mkdir(parents=True, exist_ok=True)
+        json_file = run_dir / "replay.json"
+        md_file = run_dir / "replay.md"
+
+        trace = self.to_trace()
+
+        # 1. Write replay.json
+        with open(json_file, "w", encoding="utf-8") as f:
+            json.dump(trace.to_dict(), f, indent=2)
+
+        # 2. Write replay.md
+        lines = [
+            f"# TorusGuard v0.7.0 Replayable Verification Trace: `{self.finding_id}`",
+            f"\n**Trace ID:** `{self.trace_id}`",
+            f"**Target Base URL:** `{self.target_base_url}`",
+            f"**Total Steps:** `{len(self.steps)}`",
+            f"**Description:** {self.description or 'Deterministic runtime verification trace.'}",
+            "\n---",
+            "\n## 🔁 Execution Steps\n",
+            "| Step | Action | Method | Target Path / URI | Expected Status | Assertion Pattern |",
+            "|:---:|---|:---:|---|:---:|---|",
+        ]
+        for s in self.steps:
+            lines.append(
+                f"| {s.step_number} | `{s.action_type}` | `{s.method}` | `{s.target}` | `{s.expected_status or '-'}` | `{s.expected_pattern or '-'}` |"
+            )
+
+        lines.extend([
+            "\n---",
+            "\n## 🚀 Replay Instructions",
+            "To execute this deterministic verification trace via the TorusGuard CLI:",
+            "```bash",
+            f"python -m core.replay_runner --trace runs/<run-id>/replay.json",
+            "```"
+        ])
+
+        with open(md_file, "w", encoding="utf-8") as f:
+            f.write("\n".join(lines) + "\n")
+
+        return json_file, md_file
+
+    @classmethod
+    def execute_replay(cls, trace: ReplayTrace, validator: WebValidator) -> Dict[str, Any]:
+        """
+        Re-executes the trace steps against the target application to verify reproducibility.
+        """
+        results = []
+        all_passed = True
+
+        for step in trace.steps:
+            target_url = step.target
+            if not target_url.startswith("http"):
+                target_url = f"{trace.target_base_url.rstrip('/')}/{step.target.lstrip('/')}"
+
+            status, headers, body, decision = validator.execute_probe(
+                finding_id=trace.finding_id,
+                cluster_id="cluster-replay",
+                method=step.method,
+                target_url=target_url,
+                headers=step.headers,
+                expected_status=step.expected_status
+            )
+
+            step_passed = True
+            reason = "Success"
+
+            if step.expected_status and status != step.expected_status:
+                step_passed = False
+                reason = f"Status mismatch: expected {step.expected_status}, got {status}"
+                all_passed = False
+
+            if step.expected_pattern and step.expected_pattern not in body:
+                step_passed = False
+                reason = f"Pattern mismatch: '{step.expected_pattern}' not found in response"
+                all_passed = False
+
+            results.append({
+                "step": step.step_number,
+                "passed": step_passed,
+                "status_code": status,
+                "reason": reason
+            })
+
+        return {
+            "trace_id": trace.trace_id,
+            "reproducible": all_passed,
+            "total_steps": len(trace.steps),
+            "step_results": results
+        }

package/.torusguard/core/rules_registry.py

@@ -0,0 +1,131 @@
+"""
+TorusGuard Rules Registry
+Centralized repository loading and validating canonical security rules
+across all 22 architectural rule families.
+"""
+
+from pathlib import Path
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional, Any
+import re
+
+
+CANONICAL_FAMILIES = [
+    "TG-SEC", "TG-AUTH", "TG-DB", "TG-INPUT", "TG-RATE", "TG-AGENT",
+    "TG-SSRF", "TG-WEBHOOK", "TG-WS", "TG-CSRF", "TG-GQL", "TG-SUPPLY",
+    "TG-BIZ", "TG-CACHE", "TG-CLIENT", "TG-PLATFORM", "TG-DIFF",
+    "TG-EDGE", "TG-CONT", "TG-GIT", "TG-REDOS", "TG-RAG"
+]
+
+
+@dataclass
+class CanonicalRule:
+    rule_id: str
+    family: str
+    title: str
+    severity: str
+    category: str
+    description: str
+    remediation_guidance: str = ""
+    file_path: str = ""
+    detection_patterns: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class RulesRegistry:
+    """Centralized loader and validator for TorusGuard rules."""
+
+    def __init__(self, rules_root: Optional[Path] = None):
+        self.rules_root = rules_root or self._locate_rules_dir()
+        self.rules: Dict[str, CanonicalRule] = {}
+        self.load()
+
+    def _locate_rules_dir(self) -> Path:
+        base = Path(__file__).resolve().parent.parent / ".torusguard" / "rules"
+        if base.exists():
+            return base
+        return Path.cwd() / ".torusguard" / "rules"
+
+    def load(self) -> None:
+        if not self.rules_root.exists():
+            return
+
+        for p in self.rules_root.glob("**/*.md"):
+            if p.name.startswith("README") or p.name.startswith("TORUSGUARD"):
+                continue
+
+            content = p.read_text(encoding="utf-8", errors="replace")
+            rule = self._parse_rule_markdown(p, content)
+            if rule:
+                self.rules[rule.rule_id] = rule
+
+    def _parse_rule_markdown(self, path: Path, content: str) -> Optional[CanonicalRule]:
+        filename = path.stem
+        # Extract rule_id from filename or first heading
+        rule_id_match = re.search(r"(TG-[A-Z]+-\d{3})", filename)
+        if not rule_id_match:
+            rule_id_match = re.search(r"#\s*(TG-[A-Z]+-\d{3})", content)
+        if not rule_id_match:
+            return None
+
+        rule_id = rule_id_match.group(1)
+        family = rule_id.rsplit("-", 1)[0]
+
+        # Extract title
+        title = filename.replace(rule_id, "").strip(" -_").replace("-", " ").title()
+        title_match = re.search(r"#\s*(?:TG-[A-Z]+-\d{3}[\s:—-]+)?(.+)", content)
+        if title_match:
+            cand_title = title_match.group(1).strip()
+            if cand_title and not cand_title.startswith("TG-"):
+                title = cand_title
+
+        # Severity
+        severity = "High"
+        sev_match = re.search(r"(?i)severity[:\s*|`]+(Critical|High|Medium|Low)", content)
+        if sev_match:
+            severity = sev_match.group(1).capitalize()
+
+        # Description
+        desc = ""
+        desc_match = re.search(r"(?i)(?:###?\s*Description|##\s*Overview|Summary)[:\s]*\n([^\n#]+)", content)
+        if desc_match:
+            desc = desc_match.group(1).strip()
+        else:
+            desc = title
+
+        # Remediation
+        remed = ""
+        rem_match = re.search(r"(?i)(?:###?\s*Remediation|###?\s*Mitigation|Fix)[:\s]*\n([^\n#]+)", content)
+        if rem_match:
+            remed = rem_match.group(1).strip()
+
+        return CanonicalRule(
+            rule_id=rule_id,
+            family=family,
+            title=title,
+            severity=severity,
+            category=family.replace("TG-", "").lower(),
+            description=desc,
+            remediation_guidance=remed,
+            file_path=str(path)
+        )
+
+    def get_rule(self, rule_id: str) -> Optional[CanonicalRule]:
+        return self.rules.get(rule_id)
+
+    def get_rules_by_family(self, family: str) -> List[CanonicalRule]:
+        fam_norm = family.upper()
+        if not fam_norm.startswith("TG-"):
+            fam_norm = f"TG-{fam_norm}"
+        return [r for r in self.rules.values() if r.family == fam_norm]
+
+    def get_rules_by_severity(self, severity: str) -> List[CanonicalRule]:
+        return [r for r in self.rules.values() if r.severity.lower() == severity.lower()]
+
+    def all_rules(self) -> List[CanonicalRule]:
+        return sorted(self.rules.values(), key=lambda r: r.rule_id)
+
+    def count(self) -> int:
+        return len(self.rules)

package/.torusguard/core/run_folder.py

@@ -0,0 +1,60 @@
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+class RunFolder:
+    """
+    Manages the per-run folder state and artifacts for a TorusGuard execution.
+    Creates a unique directory (e.g., .torusguard/runs/run-YYYYMMDD-HHMMSS) containing
+    findings.md, remediation.md, recheck.md, metadata.json, patches/, and logs/.
+    """
+    def __init__(self, output_root: str = ".torusguard/runs", run_name: Optional[str] = None):
+        self.output_root = Path(output_root).resolve()
+        
+        if run_name:
+            self.run_id = run_name
+        else:
+            timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+            self.run_id = f"run-{timestamp}"
+            
+        self.run_path = self.output_root / self.run_id
+        
+        # Subdirectories
+        self.patches_dir = self.run_path / "patches"
+        self.logs_dir = self.run_path / "logs"
+        
+        # Files
+        self.findings_file = self.run_path / "findings.md"
+        self.remediation_file = self.run_path / "remediation.md"
+        self.recheck_file = self.run_path / "recheck.md"
+        self.metadata_file = self.run_path / "metadata.json"
+        
+        self._initialize_folders()
+        self._write_metadata()
+
+    def _initialize_folders(self):
+        self.run_path.mkdir(parents=True, exist_ok=True)
+        self.patches_dir.mkdir(parents=True, exist_ok=True)
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+
+    def _write_metadata(self):
+        metadata = {
+            "run_id": self.run_id,
+            "created_at": datetime.now().isoformat(),
+            "status": "initialized"
+        }
+        with open(self.metadata_file, "w", encoding="utf-8") as f:
+            json.dump(metadata, f, indent=2)
+
+    def get_path(self, item: str) -> Path:
+        """Helper to get a path within the run structure."""
+        paths = {
+            "findings.md": self.findings_file,
+            "remediation.md": self.remediation_file,
+            "recheck.md": self.recheck_file,
+            "metadata.json": self.metadata_file,
+            "patches": self.patches_dir,
+            "logs": self.logs_dir
+        }
+        return paths.get(item, self.run_path / item)

package/.torusguard/core/run_manager.py

@@ -0,0 +1,163 @@
+"""
+TorusGuard v6 Run Folder & Artifact Registry Manager
+Creates and manages isolated run directories under runs/<run-id>/ containing:
+- manifest.json
+- summary.md
+- findings.md
+- remediation.md
+- apply-plan.md
+- recheck.md
+- evidence.json
+- diff-summary.md
+- changed-files.txt
+- sarif.json (optional)
+- logs/
+"""
+
+import json
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+
+
+class RunManager:
+    """
+    Manages the lifecycle of an isolated TorusGuard run directory.
+    """
+
+    def __init__(
+        self,
+        base_dir: Optional[Path] = None,
+        target_name: str = "workspace",
+        command: str = "audit",
+        run_id: Optional[str] = None,
+    ):
+        self.base_dir = base_dir or Path(".torusguard/runs")
+        self.target_name = target_name
+        self.command = command
+
+        timestamp = datetime.utcnow().strftime("%Y%m%d-%H%M%S")
+        self.run_id = run_id or f"run-{timestamp}-{target_name}"
+        self.run_path = self.base_dir / self.run_id
+
+        # Subdirectories
+        self.logs_dir = self.run_path / "logs"
+        self.patches_dir = self.run_path / "patches"
+        self.bundles_dir = self.run_path / "bundles"
+
+        # Standard Artifact Paths
+        self.manifest_file = self.run_path / "manifest.json"
+        self.summary_file = self.run_path / "summary.md"
+        self.findings_file = self.run_path / "findings.md"
+        self.remediation_file = self.run_path / "remediation.md"
+        self.apply_plan_file = self.run_path / "apply-plan.md"
+        self.recheck_file = self.run_path / "recheck.md"
+        self.evidence_file = self.run_path / "evidence.json"
+        self.diff_summary_file = self.run_path / "diff-summary.md"
+        self.changed_files_file = self.run_path / "changed-files.txt"
+        self.sarif_file = self.run_path / "sarif.json"
+
+        self._init_directories()
+
+    def _init_directories(self):
+        self.run_path.mkdir(parents=True, exist_ok=True)
+        self.logs_dir.mkdir(parents=True, exist_ok=True)
+        self.patches_dir.mkdir(parents=True, exist_ok=True)
+        self.bundles_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_git_commit(self) -> Optional[str]:
+        try:
+            res = subprocess.run(
+                ["git", "rev-parse", "HEAD"],
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+            if res.returncode == 0:
+                return res.stdout.strip()
+        except Exception:
+            pass
+        return None
+
+    def write_manifest(
+        self,
+        status_counts: Optional[Dict[str, int]] = None,
+        extra_meta: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Writes the standard manifest.json.
+        """
+        counts = status_counts or {
+            "total_findings": 0,
+            "confirmed": 0,
+            "high_confidence": 0,
+            "needs_review": 0,
+            "remediated": 0,
+            "verified_fixed": 0,
+            "regressed": 0,
+        }
+
+        manifest_data = {
+            "version": "v0.6.3",
+            "run_id": self.run_id,
+            "target_name": self.target_name,
+            "command": self.command,
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "git_commit": self.get_git_commit(),
+            "status_counts": counts,
+            "artifacts": {
+                "manifest": "manifest.json",
+                "summary": "summary.md",
+                "findings": "findings.md",
+                "remediation": "remediation.md",
+                "apply_plan": "apply-plan.md",
+                "recheck": "recheck.md",
+                "evidence": "evidence.json",
+                "diff_summary": "diff-summary.md",
+                "changed_files": "changed-files.txt",
+                "sarif": "sarif.json",
+            },
+        }
+
+        if extra_meta:
+            manifest_data.update(extra_meta)
+
+        with open(self.manifest_file, "w", encoding="utf-8") as f:
+            json.dump(manifest_data, f, indent=2)
+
+    def write_evidence(self, evidence_data: List[Dict[str, Any]]):
+        with open(self.evidence_file, "w", encoding="utf-8") as f:
+            json.dump(evidence_data, f, indent=2)
+
+    def write_changed_files(self, files: List[str]):
+        with open(self.changed_files_file, "w", encoding="utf-8") as f:
+            f.write("\n".join(files) + "\n")
+
+    def write_summary(self, content: str):
+        with open(self.summary_file, "w", encoding="utf-8") as f:
+            f.write(content)
+
+    def write_findings(self, content: str):
+        with open(self.findings_file, "w", encoding="utf-8") as f:
+            f.write(content)
+
+    def write_remediation(self, content: str):
+        with open(self.remediation_file, "w", encoding="utf-8") as f:
+            f.write(content)
+
+    def write_apply_plan(self, content: str):
+        with open(self.apply_plan_file, "w", encoding="utf-8") as f:
+            f.write(content)
+
+    def write_diff_summary(self, content: str):
+        with open(self.diff_summary_file, "w", encoding="utf-8") as f:
+            f.write(content)
+
+    def write_recheck(self, content: str):
+        with open(self.recheck_file, "w", encoding="utf-8") as f:
+            f.write(content)
+
+    def write_sarif(self, sarif_dict: Dict[str, Any]):
+        with open(self.sarif_file, "w", encoding="utf-8") as f:
+            json.dump(sarif_dict, f, indent=2)