torusguard 2.0.0-alpha → 2.1.1

package/.torusguard/core/import_resolver.py

@@ -0,0 +1,91 @@
+"""
+TorusGuard Import Resolver
+Resolves language-specific import specifiers to canonical file system paths.
+Supports Python, JavaScript, TypeScript, and Go.
+"""
+
+from pathlib import Path
+from typing import Optional, List
+
+
+COMMON_EXTENSIONS = [
+    ".py", ".ts", ".tsx", ".js", ".mjs", ".cjs", ".go"
+]
+
+
+class ImportResolver:
+    """Resolves relative and package imports to on-disk source files."""
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root.resolve()
+
+    def resolve(self, importing_file: Path, import_module: str) -> Optional[Path]:
+        """
+        Resolves `import_module` referenced by `importing_file` to an absolute Path on disk.
+        """
+        if not import_module:
+            return None
+
+        importing_file = importing_file.resolve()
+        current_dir = importing_file.parent
+
+        # 1. Relative import (e.g. ./utils, ../db, .services)
+        if import_module.startswith("."):
+            # Python style: .models or ..utils
+            if import_module.startswith(".."):
+                rel_parts = import_module.lstrip(".")
+                target_dir = current_dir.parent
+                cand = target_dir / rel_parts.replace(".", "/")
+            elif import_module.startswith("."):
+                rel_parts = import_module.lstrip(".")
+                cand = current_dir / rel_parts.replace(".", "/")
+            else:
+                cand = current_dir / import_module
+
+            resolved = self._try_extensions(cand)
+            if resolved:
+                return resolved
+
+        # 2. Direct path relative to current directory
+        direct_cand = current_dir / import_module
+        resolved = self._try_extensions(direct_cand)
+        if resolved:
+            return resolved
+
+        # 3. Project root relative import (e.g. core.taint, src.services.auth)
+        dotted_cand = self.project_root / import_module.replace(".", "/")
+        resolved = self._try_extensions(dotted_cand)
+        if resolved:
+            return resolved
+
+        # 4. Check under common subdirectories (src, app, lib, internal)
+        for sub in ("src", "app", "lib", "internal"):
+            sub_cand = self.project_root / sub / import_module.replace(".", "/")
+            resolved = self._try_extensions(sub_cand)
+            if resolved:
+                return resolved
+
+        return None
+
+    def _try_extensions(self, base_path: Path) -> Optional[Path]:
+        # Check direct file with extension already
+        if base_path.is_file():
+            return base_path
+
+        # Check with each extension
+        for ext in COMMON_EXTENSIONS:
+            cand = base_path.with_suffix(ext)
+            if cand.is_file():
+                return cand
+
+        # Check directory index / __init__
+        if base_path.is_dir():
+            py_init = base_path / "__init__.py"
+            if py_init.is_file():
+                return py_init
+            for ext in (".ts", ".js", ".tsx"):
+                idx = base_path / f"index{ext}"
+                if idx.is_file():
+                    return idx
+
+        return None

package/.torusguard/core/incremental.py

@@ -0,0 +1,102 @@
+"""
+TorusGuard Incremental Static Scanner & Hash Cache
+Identifies modified or newly added source files using cryptographic content hashes
+to enable sub-second re-scans on large codebases.
+"""
+
+from pathlib import Path
+from typing import Dict, List, Set, Optional, Any, Tuple
+import json
+import hashlib
+import time
+
+
+class IncrementalScanner:
+    """Manages file modification tracking and AST cache persistence."""
+
+    def __init__(self, target_root: Path, cache_file: Optional[Path] = None):
+        self.target_root = target_root.resolve()
+        if cache_file:
+            self.cache_file = cache_file.resolve()
+        else:
+            cache_dir = self.target_root / ".torusguard" / "cache"
+            cache_dir.mkdir(parents=True, exist_ok=True)
+            self.cache_file = cache_dir / "ast_cache.json"
+
+        self.cache_data: Dict[str, Dict[str, Any]] = self._load_cache()
+
+    def _load_cache(self) -> Dict[str, Dict[str, Any]]:
+        if self.cache_file.is_file():
+            try:
+                with open(self.cache_file, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except Exception:
+                return {}
+        return {}
+
+    def save_cache(self) -> None:
+        try:
+            self.cache_file.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.cache_file, "w", encoding="utf-8") as f:
+                json.dump(self.cache_data, f, indent=2)
+        except Exception:
+            pass
+
+    @staticmethod
+    def compute_file_hash(file_path: Path) -> str:
+        """Computes SHA256 of file content."""
+        h = hashlib.sha256()
+        try:
+            with open(file_path, "rb") as f:
+                while chunk := f.read(65536):
+                    h.update(chunk)
+            return h.hexdigest()
+        except Exception:
+            return ""
+
+    def get_changed_files(self, all_files: List[Path]) -> Tuple[List[Path], List[Path]]:
+        """
+        Compares current file hashes to cache.
+        Returns (changed_files, unchanged_files).
+        """
+        changed: List[Path] = []
+        unchanged: List[Path] = []
+
+        for f in all_files:
+            try:
+                rel_path = str(f.resolve().relative_to(self.target_root)).replace("\\", "/")
+            except Exception:
+                rel_path = str(f).replace("\\", "/")
+
+            current_hash = self.compute_file_hash(f)
+            cached_entry = self.cache_data.get(rel_path)
+
+            if cached_entry and cached_entry.get("hash") == current_hash:
+                unchanged.append(f)
+            else:
+                changed.append(f)
+
+        return changed, unchanged
+
+    def get_cached_findings(self, file_path: Path) -> List[Dict[str, Any]]:
+        try:
+            rel_path = str(file_path.resolve().relative_to(self.target_root)).replace("\\", "/")
+        except Exception:
+            rel_path = str(file_path).replace("\\", "/")
+        entry = self.cache_data.get(rel_path)
+        if entry:
+            return entry.get("findings", [])
+        return []
+
+    def update_file_cache(self, file_path: Path, findings: List[Dict[str, Any]]) -> None:
+        try:
+            rel_path = str(file_path.resolve().relative_to(self.target_root)).replace("\\", "/")
+        except Exception:
+            rel_path = str(file_path).replace("\\", "/")
+        current_hash = self.compute_file_hash(file_path)
+        self.cache_data[rel_path] = {
+            "hash": current_hash,
+            "timestamp": time.time(),
+            "findings_count": len(findings),
+            "findings": findings
+        }

package/.torusguard/core/lifecycle.py

@@ -0,0 +1,137 @@
+"""
+TorusGuard Finding Lifecycle State Machine (v0.5.1)
+Manages progression across Detect -> Classify -> Verify -> Remediate -> Recheck -> Archive.
+"""
+
+from typing import List, Tuple, Optional
+import datetime
+import hashlib
+from .models import (
+    Finding,
+    LifecycleStage,
+    FindingStatus,
+    ConfidenceBand,
+    RetestRecord,
+)
+
+
+class LifecycleTransitionError(Exception):
+    """Raised when an invalid lifecycle state transition is attempted."""
+    pass
+
+
+class FindingLifecycleManager:
+    """
+    Implements formal lifecycle progression and validation rules for TorusGuard v0.5.1 findings.
+    """
+
+    ALLOWED_TRANSITIONS = {
+        LifecycleStage.DETECT: [LifecycleStage.CLASSIFY, LifecycleStage.ARCHIVE],
+        LifecycleStage.CLASSIFY: [LifecycleStage.VERIFY, LifecycleStage.ARCHIVE],
+        LifecycleStage.VERIFY: [LifecycleStage.REMEDIATE, LifecycleStage.CLASSIFY, LifecycleStage.ARCHIVE],
+        LifecycleStage.REMEDIATE: [LifecycleStage.RECHECK, LifecycleStage.VERIFY],
+        LifecycleStage.RECHECK: [LifecycleStage.ARCHIVE, LifecycleStage.VERIFY, LifecycleStage.REMEDIATE],
+        LifecycleStage.ARCHIVE: [],  # Terminal state
+    }
+
+    @staticmethod
+    def transition(finding: Finding, target_stage: LifecycleStage, note: Optional[str] = None) -> Finding:
+        current = finding.lifecycle_stage
+        allowed = FindingLifecycleManager.ALLOWED_TRANSITIONS.get(current, [])
+
+        if target_stage not in allowed:
+            raise LifecycleTransitionError(
+                f"Invalid lifecycle transition from '{current.value}' to '{target_stage.value}'. "
+                f"Allowed target stages: {[s.value for s in allowed]}"
+            )
+
+        now = datetime.datetime.utcnow().isoformat() + "Z"
+
+        if target_stage == LifecycleStage.CLASSIFY:
+            if not finding.rule_id or not finding.category or not finding.severity:
+                raise LifecycleTransitionError("Classification requires rule_id, category, and severity.")
+            finding.status = FindingStatus.UNCONFIRMED
+
+        elif target_stage == LifecycleStage.VERIFY:
+            # Verification assertion: If no source/test evidence or evidence is insufficient, force Needs Review
+            has_sufficient_evidence = any(
+                e.is_sufficient_for_confirmed for e in finding.evidence
+            )
+            if not has_sufficient_evidence and finding.confidence.band == ConfidenceBand.CONFIRMED:
+                finding.confidence.band = ConfidenceBand.NEEDS_REVIEW
+                finding.status = FindingStatus.NEEDS_REVIEW
+            elif finding.confidence.band == ConfidenceBand.CONFIRMED:
+                finding.status = FindingStatus.CONFIRMED
+            else:
+                finding.status = FindingStatus.HIGH_CONFIDENCE if finding.confidence.score >= 70 else FindingStatus.NEEDS_REVIEW
+
+            finding.timestamps.verified_at = now
+
+        elif target_stage == LifecycleStage.REMEDIATE:
+            if not finding.remediation or not finding.remediation.recommended_fix:
+                raise LifecycleTransitionError("Remediation stage requires a complete remediation proposal.")
+            finding.status = FindingStatus.REMEDIATED
+            finding.timestamps.remediated_at = now
+
+        elif target_stage == LifecycleStage.RECHECK:
+            # Recheck requires retest record verification
+            if not finding.retest_result.retest_performed:
+                raise LifecycleTransitionError("Recheck stage requires an explicit retest to have been executed.")
+            if finding.retest_result.closure_status == FindingStatus.VERIFIED_FIXED:
+                finding.status = FindingStatus.VERIFIED_FIXED
+            finding.timestamps.retested_at = now
+
+        elif target_stage == LifecycleStage.ARCHIVE:
+            if finding.status not in (FindingStatus.VERIFIED_FIXED, FindingStatus.SUPPRESSED):
+                # Allow archive but note state
+                pass
+
+        finding.lifecycle_stage = target_stage
+        finding.timestamps.updated_at = now
+        return finding
+
+    @staticmethod
+    def execute_retest(
+        finding: Finding,
+        post_fix_code: str,
+        safe_pattern_verified: bool,
+        retest_method: str = "Differential Static Re-audit",
+        verifier_notes: str = "Verified safe via AST/pattern inspection."
+    ) -> Tuple[bool, str]:
+        """
+        Executes a formal retest on post-fix source code, hashing the evidence and updating closure status.
+        """
+        now = datetime.datetime.utcnow().isoformat() + "Z"
+        evidence_hash = hashlib.sha256(post_fix_code.strip().encode("utf-8")).hexdigest()
+
+        if safe_pattern_verified:
+            finding.retest_result = RetestRecord(
+                retest_performed=True,
+                closure_status=FindingStatus.VERIFIED_FIXED,
+                fix_applied=finding.remediation.recommended_fix,
+                retest_method=retest_method,
+                retest_evidence_hash=evidence_hash,
+                residual_risk=finding.remediation.residual_risk_notes,
+                verifier_notes=verifier_notes,
+                retest_timestamp=now,
+            )
+            finding.status = FindingStatus.VERIFIED_FIXED
+            finding.lifecycle_stage = LifecycleStage.RECHECK
+            finding.timestamps.retested_at = now
+            finding.timestamps.updated_at = now
+            return True, f"Finding {finding.finding_id} ({finding.rule_id}) successfully verified fixed. Evidence SHA256: {evidence_hash[:12]}..."
+        else:
+            finding.retest_result = RetestRecord(
+                retest_performed=True,
+                closure_status=FindingStatus.OPEN,
+                fix_applied=finding.remediation.recommended_fix,
+                retest_method=retest_method,
+                retest_evidence_hash=evidence_hash,
+                residual_risk="Remediation pattern missing or incomplete.",
+                verifier_notes="Unsafe pattern still detected in post-fix code.",
+                retest_timestamp=now,
+            )
+            finding.status = FindingStatus.OPEN
+            finding.lifecycle_stage = LifecycleStage.VERIFY
+            finding.timestamps.updated_at = now
+            return False, f"Retest failed for {finding.finding_id}: unsafe pattern remains."