torusguard 2.0.0-alpha → 2.1.1

package/.torusguard/core/runtime_evidence.py

@@ -0,0 +1,175 @@
+"""
+TorusGuard v0.7.0 Runtime Evidence Model & Secret Redaction Engine
+Captures reproducible HTTP & browser validation evidence while automatically
+redacting credentials, JWTs, API keys, and sensitive payload parameters.
+"""
+
+import re
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, asdict
+
+
+class RedactionEngine:
+    """
+    Sanitizes authorization headers, cookies, tokens, and secret parameters.
+    """
+
+    PATTERNS = [
+        (re.compile(r"Bearer\s+([A-Za-z0-9_\-\.]+)", re.IGNORECASE), "Bearer [REDACTED_TOKEN]"),
+        (re.compile(r"Basic\s+([A-Za-z0-9+/=]+)", re.IGNORECASE), "Basic [REDACTED_CREDS]"),
+        (re.compile(r"eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]+"), "[REDACTED_JWT]"),
+        (re.compile(r"sk_live_[0-9a-zA-Z]{24,}"), "sk_live_[REDACTED_KEY]"),
+        (re.compile(r"AKIA[0-9A-Z]{16}"), "AKIA[REDACTED_AWS_KEY]"),
+        (re.compile(r"([\"']?password[\"']?\s*[:=]\s*[\"'])([^\"']+)([\"'])", re.IGNORECASE), r"\1[REDACTED_PASSWORD]\3"),
+        (re.compile(r"([\"']?secret[\"']?\s*[:=]\s*[\"'])([^\"']+)([\"'])", re.IGNORECASE), r"\1[REDACTED_SECRET]\3"),
+    ]
+
+    @classmethod
+    def redact_text(cls, text: Optional[str]) -> str:
+        if not text:
+            return ""
+        redacted = text
+        for pattern, repl in cls.PATTERNS:
+            redacted = pattern.sub(repl, redacted)
+        return redacted
+
+    @classmethod
+    def redact_headers(cls, headers: Optional[Dict[str, str]]) -> Dict[str, str]:
+        if not headers:
+            return {}
+        sanitized = {}
+        sensitive_headers = {"authorization", "cookie", "set-cookie", "x-api-key", "proxy-authorization"}
+        for k, v in headers.items():
+            if k.lower() in sensitive_headers:
+                sanitized[k] = cls.redact_text(str(v))
+            else:
+                sanitized[k] = str(v)
+        return sanitized
+
+
+@dataclass
+class RuntimeEvidenceItem:
+    evidence_id: str
+    finding_id: str
+    cluster_id: str
+    timestamp: str
+    method: str
+    url: str
+    path: str
+    status_code: int
+    request_headers: Dict[str, str]
+    response_headers: Dict[str, str]
+    request_body_redacted: Optional[str]
+    response_body_snippet: str
+    exploitability_status: str
+    reproducible: bool = True
+    route_context: Optional[str] = None
+    reviewer_notes: Optional[str] = None
+    screenshot_path: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class EvidenceCollector:
+    """
+    Collects runtime HTTP request/response evidence and writes sanitized artifacts.
+    """
+
+    def __init__(self):
+        self.evidence_items: List[RuntimeEvidenceItem] = []
+        self.requests_log: List[Dict[str, Any]] = []
+        self.responses_log: List[Dict[str, Any]] = []
+
+    def record_interaction(
+        self,
+        finding_id: str,
+        cluster_id: str,
+        method: str,
+        url: str,
+        path: str,
+        status_code: int,
+        req_headers: Dict[str, str],
+        resp_headers: Dict[str, str],
+        req_body: Optional[str],
+        resp_body: Optional[str],
+        exploitability_status: str,
+        route_context: Optional[str] = None,
+        reviewer_notes: Optional[str] = None,
+        screenshot_path: Optional[str] = None,
+    ) -> RuntimeEvidenceItem:
+        now = datetime.now(timezone.utc).isoformat()
+        ev_id = f"EV-RT-{len(self.evidence_items) + 1:04d}"
+
+        sanitized_req_headers = RedactionEngine.redact_headers(req_headers)
+        sanitized_resp_headers = RedactionEngine.redact_headers(resp_headers)
+        sanitized_req_body = RedactionEngine.redact_text(req_body) if req_body else None
+        snippet = RedactionEngine.redact_text((resp_body or "")[:500])
+
+        item = RuntimeEvidenceItem(
+            evidence_id=ev_id,
+            finding_id=finding_id,
+            cluster_id=cluster_id,
+            timestamp=now,
+            method=method.upper(),
+            url=url,
+            path=path,
+            status_code=status_code,
+            request_headers=sanitized_req_headers,
+            response_headers=sanitized_resp_headers,
+            request_body_redacted=sanitized_req_body,
+            response_body_snippet=snippet,
+            exploitability_status=exploitability_status,
+            reproducible=True,
+            route_context=route_context,
+            reviewer_notes=reviewer_notes,
+            screenshot_path=screenshot_path,
+        )
+
+        self.evidence_items.append(item)
+
+        # Append to logs
+        self.requests_log.append({
+            "evidence_id": ev_id,
+            "timestamp": now,
+            "method": method.upper(),
+            "url": url,
+            "headers": sanitized_req_headers,
+            "body": sanitized_req_body,
+        })
+        self.responses_log.append({
+            "evidence_id": ev_id,
+            "timestamp": now,
+            "status_code": status_code,
+            "headers": sanitized_resp_headers,
+            "body_snippet": snippet,
+        })
+
+        return item
+
+    def write_artifacts(self, run_dir: Path) -> Dict[str, Path]:
+        """
+        Emits requests.json, responses.json, and runtime-evidence.json.
+        """
+        run_dir.mkdir(parents=True, exist_ok=True)
+        req_file = run_dir / "requests.json"
+        resp_file = run_dir / "responses.json"
+        ev_file = run_dir / "runtime-evidence.json"
+
+        with open(req_file, "w", encoding="utf-8") as f:
+            json.dump(self.requests_log, f, indent=2)
+
+        with open(resp_file, "w", encoding="utf-8") as f:
+            json.dump(self.responses_log, f, indent=2)
+
+        with open(ev_file, "w", encoding="utf-8") as f:
+            json.dump([item.to_dict() for item in self.evidence_items], f, indent=2)
+
+        return {
+            "requests": req_file,
+            "responses": resp_file,
+            "evidence": ev_file,
+        }

package/.torusguard/core/runtime_validator.py

@@ -0,0 +1,246 @@
+"""
+TorusGuard v0.7.0 Web Validation Engine
+Executes authorized HTTP probes against running applications, captures requests/responses,
+maintains session state across endpoints, and strictly abides by scope & safety gates.
+"""
+
+import json
+import urllib.request
+import urllib.error
+from urllib.parse import urljoin, urlparse
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Tuple
+from dataclasses import dataclass, field
+
+from core.authorization import AuthorizationRecord, AuthorizationManager, AuthorizationError
+from core.safety_gate import SafetyGate, SafetyDecision, SafetyReviewLevel
+from core.runtime_evidence import EvidenceCollector, RuntimeEvidenceItem
+
+
+@dataclass
+class SessionState:
+    session_id: str
+    cookies: Dict[str, str] = field(default_factory=dict)
+    custom_headers: Dict[str, str] = field(default_factory=dict)
+    notes: List[str] = field(default_factory=list)
+
+    def add_cookie(self, name: str, value: str):
+        self.cookies[name] = value
+
+    def add_header(self, name: str, value: str):
+        self.custom_headers[name] = value
+
+    def log_note(self, note: str):
+        self.notes.append(note)
+
+    def get_cookie_header(self) -> Optional[str]:
+        if not self.cookies:
+            return None
+        return "; ".join(f"{k}={v}" for k, v in self.cookies.items())
+
+
+class WebValidator:
+    """
+    Executes scoped and authorized HTTP interactions against target applications.
+    """
+
+    def __init__(
+        self,
+        auth_record: AuthorizationRecord,
+        evidence_collector: Optional[EvidenceCollector] = None,
+        timeout_seconds: int = 5,
+        max_requests: int = 100
+    ):
+        self.auth = auth_record
+        self.evidence_collector = evidence_collector or EvidenceCollector()
+        self.timeout = timeout_seconds
+        self.max_requests = max_requests
+        self.request_count = 0
+        self.session = SessionState(session_id="session-default")
+        self.validation_logs: List[Dict[str, Any]] = []
+
+    def execute_probe(
+        self,
+        finding_id: str,
+        cluster_id: str,
+        method: str,
+        target_url: str,
+        headers: Optional[Dict[str, str]] = None,
+        body: Optional[str] = None,
+        expected_status: Optional[int] = None,
+        pre_approved: bool = False,
+        route_context: Optional[str] = None,
+    ) -> Tuple[int, Dict[str, str], str, SafetyDecision]:
+        """
+        Validates scope and safety before dispatching an HTTP probe.
+        """
+        # 1. Authorization check
+        AuthorizationManager.check_authorized_or_raise(target_url, self.auth, method=method)
+
+        # 2. Budget check
+        if self.request_count >= self.max_requests:
+            raise AuthorizationError(f"Request budget exceeded (max {self.max_requests} requests reached).")
+        self.request_count += 1
+
+        # 3. Safety Gate Evaluation
+        parsed = urlparse(target_url)
+        path = parsed.path or "/"
+        action_id = f"ACT-{self.request_count:03d}"
+        decision = SafetyGate.evaluate_action(action_id, method, path, context=route_context, pre_approved=pre_approved)
+
+        if not decision.allowed_to_proceed:
+            # Action blocked by safety gate
+            self.session.log_note(f"Probe to {method} {target_url} blocked by Safety Gate ({decision.review_level}).")
+            self.validation_logs.append({
+                "action_id": action_id,
+                "status": "BLOCKED",
+                "review_level": decision.review_level,
+                "rationale": decision.rationale,
+                "url": target_url,
+            })
+            return 0, {}, "BLOCKED_BY_SAFETY_GATE", decision
+
+        # 4. Prepare Headers (inject session cookies and custom headers)
+        merged_headers = self._prepare_request_headers(headers)
+
+        # 5. Dispatch HTTP Request
+        status_code, resp_headers, resp_body = self._dispatch_http(
+            method=method,
+            target_url=target_url,
+            headers=merged_headers,
+            body=body
+        )
+
+        # 6. Record interaction in Evidence Collector
+        exploit_status = "Runtime Confirmed" if (expected_status and status_code == expected_status) else "Runtime Likely"
+        self.evidence_collector.record_interaction(
+            finding_id=finding_id,
+            cluster_id=cluster_id,
+            method=method,
+            url=target_url,
+            path=path,
+            status_code=status_code,
+            req_headers=merged_headers,
+            resp_headers=resp_headers,
+            req_body=body,
+            resp_body=resp_body,
+            exploitability_status=exploit_status,
+            route_context=route_context,
+            reviewer_notes=f"HTTP {status_code} received from {path}"
+        )
+
+        self.validation_logs.append({
+            "action_id": action_id,
+            "status": "COMPLETED",
+            "method": method.upper(),
+            "url": target_url,
+            "status_code": status_code,
+            "review_level": decision.review_level
+        })
+
+        return status_code, resp_headers, resp_body, decision
+
+    def _prepare_request_headers(self, headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """Merges session headers, cookies, and transparent TorusGuard audit headers."""
+        merged_headers = dict(self.session.custom_headers)
+        if headers:
+            merged_headers.update(headers)
+
+        cookie_str = self.session.get_cookie_header()
+        if cookie_str and "Cookie" not in merged_headers:
+            merged_headers["Cookie"] = cookie_str
+
+        merged_headers["User-Agent"] = "TorusGuard-RuntimeValidator/0.7.0 (Authorized Audit)"
+        merged_headers["X-TorusGuard-AuthID"] = self.auth.authorization_id
+        return merged_headers
+
+    def _dispatch_http(
+        self, method: str, target_url: str, headers: Dict[str, str], body: Optional[str] = None
+    ) -> Tuple[int, Dict[str, str], str]:
+        """Executes low-level HTTP interaction and parses response cookies/errors."""
+        status_code = 0
+        resp_headers: Dict[str, str] = {}
+        resp_body = ""
+
+        req_data = body.encode("utf-8") if body else None
+        req = urllib.request.Request(target_url, data=req_data, headers=headers, method=method.upper())
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                status_code = resp.getcode()
+                resp_headers = dict(resp.headers)
+                resp_body = resp.read().decode("utf-8", errors="replace")
+
+                if "Set-Cookie" in resp_headers:
+                    self._parse_and_store_cookies(resp_headers["Set-Cookie"])
+
+        except urllib.error.HTTPError as e:
+            status_code = e.code
+            resp_headers = dict(e.headers)
+            resp_body = e.read().decode("utf-8", errors="replace")
+        except urllib.error.URLError as e:
+            status_code = 599
+            resp_body = f"Network connection error: {e.reason}"
+        except Exception as e:
+            status_code = 599
+            resp_body = f"Unexpected runtime error: {str(e)}"
+
+        return status_code, resp_headers, resp_body
+
+    def _parse_and_store_cookies(self, cookie_header: str):
+        for part in cookie_header.split(","):
+            cookie_pair = part.split(";")[0].strip()
+            if "=" in cookie_pair:
+                k, v = cookie_pair.split("=", 1)
+                self.session.add_cookie(k.strip(), v.strip())
+
+    def write_report_artifacts(self, run_dir: Path) -> Dict[str, Path]:
+        """
+        Emits web-validation.md, session-notes.md, and evidence logs.
+        """
+        run_dir.mkdir(parents=True, exist_ok=True)
+        ev_artifacts = self.evidence_collector.write_artifacts(run_dir)
+
+        # 1. web-validation.md
+        wv_file = run_dir / "web-validation.md"
+        lines = [
+            "# TorusGuard v0.7.0 Web Validation Summary",
+            f"\n**Authorization ID:** `{self.auth.authorization_id}`",
+            f"**Target:** `{self.auth.target_name}`",
+            f"**Total Requests Dispatched:** `{self.request_count}` / `{self.max_requests}`",
+            "\n---",
+            "\n## 🌐 Interaction Audit Log\n",
+            "| Action ID | Method | Target URL | HTTP Status | Safety Review Level | Execution Status |",
+            "|---|---|---|:---:|:---:|:---:|",
+        ]
+        for log in self.validation_logs:
+            lines.append(
+                f"| `{log.get('action_id')}` | `{log.get('method', 'N/A')}` | `{log.get('url')}` | `{log.get('status_code', '-')}` | `{log.get('review_level')}` | **{log.get('status')}** |"
+            )
+
+        with open(wv_file, "w", encoding="utf-8") as f:
+            f.write("\n".join(lines) + "\n")
+
+        # 2. session-notes.md
+        session_file = run_dir / "session-notes.md"
+        s_lines = [
+            "# TorusGuard v0.7.0 Runtime Session Notes",
+            f"\n**Session Identifier:** `{self.session.session_id}`",
+            f"**Captured Cookies:** `{len(self.session.cookies)}` active cookies",
+            f"**Custom Headers Set:** `{list(self.session.custom_headers.keys())}`",
+            "\n### Session Event Timeline\n",
+        ]
+        if self.session.notes:
+            for note in self.session.notes:
+                s_lines.append(f"- {note}")
+        else:
+            s_lines.append("- No manual session interventions recorded.")
+
+        with open(session_file, "w", encoding="utf-8") as f:
+            f.write("\n".join(s_lines) + "\n")
+
+        return {
+            "web_validation": wv_file,
+            "session_notes": session_file,
+            **ev_artifacts
+        }

package/.torusguard/core/safety_gate.py

@@ -0,0 +1,139 @@
+"""
+TorusGuard v0.7.0 Safety & Approval Gates
+Enforces explicit governance gates for sensitive endpoints, privileged actions,
+and state-changing runtime operations before execution.
+"""
+
+import json
+from enum import Enum
+from pathlib import Path
+from typing import Dict, Any, List, Optional
+from dataclasses import dataclass, asdict
+
+
+class SafetyReviewLevel(str, Enum):
+    AUTO_ALLOWED = "Auto-Allowed"
+    APPROVAL_REQUIRED = "Approval Required"
+    MANUAL_ONLY = "Manual Only"
+
+
+@dataclass
+class SafetyDecision:
+    action_id: str
+    method: str
+    target_path: str
+    review_level: str
+    allowed_to_proceed: bool
+    rationale: str
+    requires_human_approval: bool
+    escalation_reasons: List[str]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class SafetyGate:
+    """
+    Evaluates runtime actions and determines whether they are auto-allowed,
+    require explicit human/agent approval, or are strictly manual-only.
+    """
+
+    CRITICAL_MANUAL_PATHS = [
+        "/admin/delete",
+        "/admin/users/delete",
+        "/system/shutdown",
+        "/system/reset",
+        "/api/v1/database/drop",
+        "/billing/charge",
+        "/auth/password-reset-confirm"
+    ]
+
+    SENSITIVE_APPROVAL_KEYWORDS = [
+        "auth",
+        "login",
+        "session",
+        "token",
+        "tenant",
+        "upload",
+        "transfer",
+        "credential",
+        "secret",
+        "role"
+    ]
+
+    @classmethod
+    def evaluate_action(
+        cls,
+        action_id: str,
+        method: str,
+        path: str,
+        context: Optional[str] = None,
+        pre_approved: bool = False
+    ) -> SafetyDecision:
+        """
+        Evaluates safety risk and returns a formal SafetyDecision.
+        """
+        method_upper = method.upper()
+        path_lower = path.lower()
+        context_lower = (context or "").lower()
+        escalations = []
+
+        # 1. Check for Critical / Destructive paths -> Manual Only
+        for crit in cls.CRITICAL_MANUAL_PATHS:
+            if crit in path_lower or crit in context_lower:
+                escalations.append(f"Matches critical path/action pattern '{crit}'")
+                return SafetyDecision(
+                    action_id=action_id,
+                    method=method_upper,
+                    target_path=path,
+                    review_level=SafetyReviewLevel.MANUAL_ONLY.value,
+                    allowed_to_proceed=False,
+                    rationale="High-risk destructive/privileged path; automated execution blocked.",
+                    requires_human_approval=True,
+                    escalation_reasons=escalations
+                )
+
+        # 2. Check for State-Changing methods or Sensitive keywords -> Approval Required
+        is_state_changing = method_upper in ["POST", "PUT", "DELETE", "PATCH"]
+        if is_state_changing:
+            escalations.append(f"HTTP method '{method_upper}' can alter server state")
+
+        for kw in cls.SENSITIVE_APPROVAL_KEYWORDS:
+            if kw in path_lower or kw in context_lower:
+                escalations.append(f"Touches sensitive security context keyword '{kw}'")
+
+        if escalations:
+            # Requires approval
+            allowed = pre_approved
+            rationale = "Pre-approved by security engineer" if pre_approved else "Requires explicit approval before execution"
+            return SafetyDecision(
+                action_id=action_id,
+                method=method_upper,
+                target_path=path,
+                review_level=SafetyReviewLevel.APPROVAL_REQUIRED.value,
+                allowed_to_proceed=allowed,
+                rationale=rationale,
+                requires_human_approval=not pre_approved,
+                escalation_reasons=escalations
+            )
+
+        # 3. Read-only standard path -> Auto-Allowed
+        return SafetyDecision(
+            action_id=action_id,
+            method=method_upper,
+            target_path=path,
+            review_level=SafetyReviewLevel.AUTO_ALLOWED.value,
+            allowed_to_proceed=True,
+            rationale="Read-only query to non-sensitive in-scope endpoint.",
+            requires_human_approval=False,
+            escalation_reasons=[]
+        )
+
+    @staticmethod
+    def record_decisions(run_dir: Path, decisions: List[SafetyDecision]) -> Path:
+        run_dir.mkdir(parents=True, exist_ok=True)
+        decision_file = run_dir / "safety-decisions.json"
+        data = [d.to_dict() for d in decisions]
+        with open(decision_file, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+        return decision_file