torusguard 2.0.0-alpha → 2.1.1

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

@@ -0,0 +1,104 @@
+"""
+TorusGuard v0.7.0 Role-Based Multi-Agent Workflow Engine
+Coordinates explicit handoff contracts between Profiler, Validator, Remediator,
+and Reviewer agent roles, ensuring strict authority separation and full auditability.
+"""
+
+import json
+from enum import Enum
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Any, List, Optional, Tuple
+from dataclasses import dataclass, asdict
+
+
+class AgentRole(str, Enum):
+    PROFILER = "Profiler"
+    VALIDATOR = "Validator"
+    REMEDIATOR = "Remediator"
+    REVIEWER = "Reviewer"
+
+
+@dataclass
+class RoleHandoff:
+    handoff_id: str
+    from_role: str
+    to_role: str
+    timestamp: str
+    contract_goal: str
+    inputs_passed: Dict[str, Any]
+    outputs_produced: Dict[str, Any]
+    status: str = "Completed"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class RoleOrchestrator:
+    """
+    Coordinates the 4-role multi-agent workflow and records audit logs.
+    """
+
+    def __init__(self, run_id: str):
+        self.run_id = run_id
+        self.handoffs: List[RoleHandoff] = []
+
+    def record_handoff(
+        self,
+        from_role: AgentRole,
+        to_role: AgentRole,
+        contract_goal: str,
+        inputs: Dict[str, Any],
+        outputs: Dict[str, Any]
+    ) -> RoleHandoff:
+        now = datetime.now(timezone.utc).isoformat()
+        h_id = f"HDF-{len(self.handoffs) + 1:02d}"
+        handoff = RoleHandoff(
+            handoff_id=h_id,
+            from_role=from_role.value,
+            to_role=to_role.value,
+            timestamp=now,
+            contract_goal=contract_goal,
+            inputs_passed=inputs,
+            outputs_produced=outputs,
+            status="Completed"
+        )
+        self.handoffs.append(handoff)
+        return handoff
+
+    def write_artifacts(self, run_dir: Path) -> Tuple[Path, Path]:
+        run_dir.mkdir(parents=True, exist_ok=True)
+        audit_file = run_dir / "role-audit.json"
+        handoff_file = run_dir / "agent-handoffs.md"
+
+        # 1. role-audit.json
+        with open(audit_file, "w", encoding="utf-8") as f:
+            json.dump([h.to_dict() for h in self.handoffs], f, indent=2)
+
+        # 2. agent-handoffs.md
+        lines = [
+            "# TorusGuard v0.7.0 Multi-Agent Role Handoff & Governance Trail",
+            f"\n**Run Identifier:** `{self.run_id}`",
+            f"**Total Role Handoffs:** `{len(self.handoffs)}`",
+            "\n---",
+            "\n## 👥 Multi-Agent Responsibility Matrix\n",
+            "| Agent Role | Explicit Authority & Purpose | Forbidden Actions |",
+            "|---|---|---|",
+            "| **🔍 Profiler** | Detects tech stack, framework versions, route ASTs, and storage boundaries. | Cannot execute active probes or generate code patches. |",
+            "| **⚡ Validator** | Executes authorized, bounded runtime HTTP/browser probes; gathers evidence. | Cannot apply code changes or override reviewer policies. |",
+            "| **🛠️ Remediator** | Formulates minimal bounded remediation bundles enriched with runtime context. | Cannot dispatch runtime network probes or declare final sign-off. |",
+            "| **🛡️ Reviewer** | Verifies technical evidence, reviews safety decisions, and issues sign-off. | Does not execute probes or author patches. |",
+            "\n---",
+            "\n## 🔄 Chronological Handoff Log\n",
+            "| Handoff ID | From Role | To Role | Contract Goal | Timestamp | Status |",
+            "|---|---|---|---|---|:---:|",
+        ]
+        for h in self.handoffs:
+            lines.append(
+                f"| `{h.handoff_id}` | **{h.from_role}** | **{h.to_role}** | {h.contract_goal} | `{h.timestamp}` | ✅ {h.status} |"
+            )
+
+        with open(handoff_file, "w", encoding="utf-8") as f:
+            f.write("\n".join(lines) + "\n")
+
+        return audit_file, handoff_file

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

@@ -0,0 +1,283 @@
+"""
+TorusGuard Polyglot AST Walker
+Extracts structured primitives (FunctionCall, Assignment, ImportStatement, StringLiteral)
+from Tree-sitter AST nodes and fallback parsers across polyglot languages.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Any, Optional
+
+
+@dataclass
+class FunctionCall:
+    name: str
+    full_call: str
+    arguments: List[str]
+    line_number: int
+    column: int
+    receiver: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Assignment:
+    target: str
+    value_expression: str
+    line_number: int
+    column: int
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class ImportStatement:
+    module: str
+    imported_names: List[str]
+    alias_map: Dict[str, str] = field(default_factory=dict)
+    line_number: int = 0
+    is_relative: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class StringLiteral:
+    value: str
+    line_number: int
+    column: int
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class TreeSitterWalker:
+    """
+    Traverses Tree-sitter parse trees and extracts normalized language constructs.
+    """
+
+    @staticmethod
+    def extract_function_calls(root_node, source_bytes: bytes) -> List[FunctionCall]:
+        calls: List[FunctionCall] = []
+
+        def visit(node):
+            # Python: call -> function, arguments
+            # JS/TS: call_expression -> function, arguments
+            # Go: call_expression -> function, argument_list
+            if node.type in ("call", "call_expression"):
+                func_child = node.child_by_field_name("function")
+                args_child = node.child_by_field_name("arguments") or node.child_by_field_name("argument_list")
+
+                func_name = ""
+                receiver = None
+                if func_child:
+                    func_text = source_bytes[func_child.start_byte:func_child.end_byte].decode("utf-8", errors="replace")
+                    func_name = func_text
+                    if "." in func_text:
+                        parts = func_text.split(".")
+                        receiver = ".".join(parts[:-1])
+
+                args_list: List[str] = []
+                if args_child:
+                    for ch in args_child.children:
+                        if ch.type not in (",", "(", ")"):
+                            arg_text = source_bytes[ch.start_byte:ch.end_byte].decode("utf-8", errors="replace").strip()
+                            if arg_text:
+                                args_list.append(arg_text)
+
+                line_num = node.start_point[0] + 1
+                col = node.start_point[1]
+                call_text = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+
+                calls.append(FunctionCall(
+                    name=func_name,
+                    full_call=call_text,
+                    arguments=args_list,
+                    line_number=line_num,
+                    column=col,
+                    receiver=receiver
+                ))
+
+            for ch in node.children:
+                visit(ch)
+
+        visit(root_node)
+        return calls
+
+    @staticmethod
+    def extract_assignments(root_node, source_bytes: bytes) -> List[Assignment]:
+        assignments: List[Assignment] = []
+
+        def visit(node):
+            # Python: assignment -> left, right
+            # JS/TS: variable_declarator (name, value), assignment_expression (left, right)
+            # Go: short_var_declaration (left, right), assignment_statement (left, right)
+            target = ""
+            val_expr = ""
+            line_num = node.start_point[0] + 1
+            col = node.start_point[1]
+
+            if node.type == "assignment":  # Python
+                left = node.child_by_field_name("left")
+                right = node.child_by_field_name("right")
+                if left and right:
+                    target = source_bytes[left.start_byte:left.end_byte].decode("utf-8", errors="replace").strip()
+                    val_expr = source_bytes[right.start_byte:right.end_byte].decode("utf-8", errors="replace").strip()
+                    assignments.append(Assignment(target=target, value_expression=val_expr, line_number=line_num, column=col))
+
+            elif node.type == "variable_declarator":  # JS/TS
+                name = node.child_by_field_name("name")
+                val = node.child_by_field_name("value")
+                if name:
+                    target = source_bytes[name.start_byte:name.end_byte].decode("utf-8", errors="replace").strip()
+                    if val:
+                        val_expr = source_bytes[val.start_byte:val.end_byte].decode("utf-8", errors="replace").strip()
+                    assignments.append(Assignment(target=target, value_expression=val_expr, line_number=line_num, column=col))
+
+            elif node.type == "assignment_expression":  # JS/TS
+                left = node.child_by_field_name("left")
+                right = node.child_by_field_name("right")
+                if left and right:
+                    target = source_bytes[left.start_byte:left.end_byte].decode("utf-8", errors="replace").strip()
+                    val_expr = source_bytes[right.start_byte:right.end_byte].decode("utf-8", errors="replace").strip()
+                    assignments.append(Assignment(target=target, value_expression=val_expr, line_number=line_num, column=col))
+
+            elif node.type in ("short_var_declaration", "assignment_statement"):  # Go
+                left = node.child_by_field_name("left")
+                right = node.child_by_field_name("right")
+                if left and right:
+                    target = source_bytes[left.start_byte:left.end_byte].decode("utf-8", errors="replace").strip()
+                    val_expr = source_bytes[right.start_byte:right.end_byte].decode("utf-8", errors="replace").strip()
+                    assignments.append(Assignment(target=target, value_expression=val_expr, line_number=line_num, column=col))
+
+            for ch in node.children:
+                visit(ch)
+
+        visit(root_node)
+        return assignments
+
+    @staticmethod
+    def extract_imports(root_node, source_bytes: bytes, language: str) -> List[ImportStatement]:
+        imports: List[ImportStatement] = []
+
+        def visit(node):
+            line_num = node.start_point[0] + 1
+
+            # Python imports
+            if node.type == "import_statement":
+                raw = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace").strip()
+                # e.g. import os, sys as s
+                names = []
+                alias_map = {}
+                for ch in node.children:
+                    if ch.type == "dotted_name":
+                        mod = source_bytes[ch.start_byte:ch.end_byte].decode("utf-8", errors="replace").strip()
+                        names.append(mod)
+                    elif ch.type == "aliased_import":
+                        n = ch.child_by_field_name("name")
+                        a = ch.child_by_field_name("alias")
+                        if n and a:
+                            name_str = source_bytes[n.start_byte:n.end_byte].decode("utf-8", errors="replace").strip()
+                            alias_str = source_bytes[a.start_byte:a.end_byte].decode("utf-8", errors="replace").strip()
+                            names.append(name_str)
+                            alias_map[alias_str] = name_str
+                for n in names:
+                    imports.append(ImportStatement(module=n, imported_names=[n], alias_map=alias_map, line_number=line_num))
+
+            elif node.type == "import_from_statement":
+                # from module import a, b as c
+                module_name = ""
+                mod_child = node.child_by_field_name("module_name")
+                if mod_child:
+                    module_name = source_bytes[mod_child.start_byte:mod_child.end_byte].decode("utf-8", errors="replace").strip()
+                names = []
+                alias_map = {}
+                for ch in node.children:
+                    if ch.type == "dotted_name" and ch != mod_child:
+                        names.append(source_bytes[ch.start_byte:ch.end_byte].decode("utf-8", errors="replace").strip())
+                    elif ch.type == "aliased_import":
+                        n = ch.child_by_field_name("name")
+                        a = ch.child_by_field_name("alias")
+                        if n and a:
+                            n_str = source_bytes[n.start_byte:n.end_byte].decode("utf-8", errors="replace").strip()
+                            a_str = source_bytes[a.start_byte:a.end_byte].decode("utf-8", errors="replace").strip()
+                            names.append(n_str)
+                            alias_map[a_str] = n_str
+                is_rel = module_name.startswith(".")
+                imports.append(ImportStatement(
+                    module=module_name,
+                    imported_names=names,
+                    alias_map=alias_map,
+                    line_number=line_num,
+                    is_relative=is_rel
+                ))
+
+            # JS/TS imports: import_statement
+            elif node.type == "import_statement":
+                raw = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace").strip()
+                source_child = node.child_by_field_name("source")
+                source_mod = ""
+                if source_child:
+                    source_mod = source_bytes[source_child.start_byte:source_child.end_byte].decode("utf-8", errors="replace").strip().strip("'\"")
+                names = []
+                alias_map = {}
+                for ch in node.children:
+                    if ch.type == "import_clause":
+                        clause_str = source_bytes[ch.start_byte:ch.end_byte].decode("utf-8", errors="replace").strip()
+                        names.append(clause_str)
+                is_rel = source_mod.startswith(".")
+                imports.append(ImportStatement(
+                    module=source_mod,
+                    imported_names=names,
+                    alias_map=alias_map,
+                    line_number=line_num,
+                    is_relative=is_rel
+                ))
+
+            # Go imports: import_declaration
+            elif node.type == "import_declaration":
+                for ch in node.children:
+                    if ch.type in ("import_spec", "import_spec_list"):
+                        for spec in (ch.children if ch.type == "import_spec_list" else [ch]):
+                            if spec.type == "import_spec":
+                                path_child = spec.child_by_field_name("path")
+                                if path_child:
+                                    path_str = source_bytes[path_child.start_byte:path_child.end_byte].decode("utf-8", errors="replace").strip().strip('"')
+                                    name_child = spec.child_by_field_name("name")
+                                    alias = ""
+                                    if name_child:
+                                        alias = source_bytes[name_child.start_byte:name_child.end_byte].decode("utf-8", errors="replace").strip()
+                                    alias_map = {alias: path_str} if alias else {}
+                                    imports.append(ImportStatement(
+                                        module=path_str,
+                                        imported_names=[path_str],
+                                        alias_map=alias_map,
+                                        line_number=spec.start_point[0] + 1
+                                    ))
+
+            for ch in node.children:
+                visit(ch)
+
+        visit(root_node)
+        return imports
+
+    @staticmethod
+    def extract_string_literals(root_node, source_bytes: bytes) -> List[StringLiteral]:
+        literals: List[StringLiteral] = []
+
+        def visit(node):
+            if node.type in ("string", "string_literal", "raw_string_literal", "template_string"):
+                text = source_bytes[node.start_byte:node.end_byte].decode("utf-8", errors="replace")
+                literals.append(StringLiteral(
+                    value=text.strip("\"'`"),
+                    line_number=node.start_point[0] + 1,
+                    column=node.start_point[1]
+                ))
+            for ch in node.children:
+                visit(ch)
+
+        visit(root_node)
+        return literals

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

@@ -0,0 +1,218 @@
+"""
+TorusGuard v0.7.0 Authorization & Scope Enforcement Engine
+Enforces explicit target authorization and scope boundaries before any runtime validation.
+No runtime HTTP or browser interaction is permitted without valid, non-expired authorization.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Optional, Dict, Any, Tuple
+from dataclasses import dataclass, asdict
+from urllib.parse import urlparse
+
+
+class AuthorizationError(PermissionError):
+    """Raised when runtime validation is attempted without valid authorization or outside approved scope."""
+    pass
+
+
+@dataclass
+class TargetScope:
+    target_hosts: List[str]
+    allowed_path_prefixes: List[str]
+    forbidden_paths: List[str]
+    valid_from: str
+    valid_until: str
+    max_depth: int = 3
+    max_requests: int = 100
+    allow_state_changing_methods: bool = False
+    allowed_issue_classes: Optional[List[str]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "TargetScope":
+        return cls(
+            target_hosts=data.get("target_hosts", []),
+            allowed_path_prefixes=data.get("allowed_path_prefixes", ["/"]),
+            forbidden_paths=data.get("forbidden_paths", ["/admin/delete", "/system/shutdown"]),
+            valid_from=data.get("valid_from", ""),
+            valid_until=data.get("valid_until", ""),
+            max_depth=data.get("max_depth", 3),
+            max_requests=data.get("max_requests", 100),
+            allow_state_changing_methods=data.get("allow_state_changing_methods", False),
+            allowed_issue_classes=data.get("allowed_issue_classes", [
+                "auth_bypass",
+                "tenant_isolation",
+                "header_trust",
+                "path_traversal",
+                "debug_exposure"
+            ])
+        )
+
+
+@dataclass
+class AuthorizationRecord:
+    authorization_id: str
+    target_name: str
+    authorized_by: str
+    authorization_type: str  # "target_owner", "written_authorization", "ci_sandboxed_test"
+    scope: TargetScope
+    created_at: str = ""
+
+    def __post_init__(self):
+        if not self.created_at:
+            self.created_at = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        d["scope"] = self.scope.to_dict()
+        return d
+
+
+class AuthorizationManager:
+    """
+    Validates, manages, and stores target authorizations in isolated run folders.
+    """
+
+    @staticmethod
+    def is_scope_active(scope: TargetScope) -> Tuple[bool, str]:
+        now = datetime.now(timezone.utc)
+        if scope.valid_from:
+            try:
+                v_from = datetime.fromisoformat(scope.valid_from.replace("Z", "+00:00"))
+                if now < v_from:
+                    return False, f"Authorization not yet active (starts {scope.valid_from})"
+            except Exception:
+                pass
+        if scope.valid_until:
+            try:
+                v_until = datetime.fromisoformat(scope.valid_until.replace("Z", "+00:00"))
+                if now > v_until:
+                    return False, f"Authorization expired at {scope.valid_until}"
+            except Exception:
+                pass
+        return True, "Authorization active"
+
+    @classmethod
+    def _match_host(cls, host: str, target_hosts: List[str]) -> bool:
+        """Checks if host matches approved host or host:port patterns."""
+        for approved in target_hosts:
+            approved_lower = approved.lower()
+            if host == approved_lower or host.startswith(approved_lower + ":") or approved_lower.startswith(host + ":"):
+                return True
+        return False
+
+    @classmethod
+    def _match_forbidden_path(cls, path: str, forbidden_paths: List[str]) -> Optional[str]:
+        """Returns matching forbidden path prefix if any, else None."""
+        for forbidden in forbidden_paths:
+            if path.startswith(forbidden):
+                return forbidden
+        return None
+
+    @classmethod
+    def _match_allowed_prefix(cls, path: str, allowed_prefixes: List[str]) -> bool:
+        """Checks if path matches at least one allowed prefix."""
+        for prefix in allowed_prefixes:
+            if path.startswith(prefix):
+                return True
+        return False
+
+    @classmethod
+    def validate_url(cls, url: str, scope: TargetScope) -> Tuple[bool, str]:
+        """
+        Ensures target URL is strictly inside approved hosts, allowed path prefixes,
+        and not in forbidden paths.
+        """
+        parsed = urlparse(url)
+        host = parsed.netloc.lower()
+        if not host:
+            return False, f"Invalid URL (missing host): {url}"
+
+        # 1. Match approved host
+        if not cls._match_host(host, scope.target_hosts):
+            return False, f"Host '{host}' is NOT in approved target_hosts: {scope.target_hosts}"
+
+        # 2. Check forbidden paths
+        path = parsed.path or "/"
+        matched_forbidden = cls._match_forbidden_path(path, scope.forbidden_paths)
+        if matched_forbidden:
+            return False, f"Path '{path}' matches forbidden path '{matched_forbidden}'"
+
+        # 3. Check allowed path prefixes
+        if not cls._match_allowed_prefix(path, scope.allowed_path_prefixes):
+            return False, f"Path '{path}' does NOT match any allowed_path_prefixes: {scope.allowed_path_prefixes}"
+
+        # 4. Check TTL
+        active, reason = cls.is_scope_active(scope)
+        if not active:
+            return False, reason
+
+        return True, "URL within authorized scope"
+
+    @classmethod
+    def check_authorized_or_raise(cls, url: str, auth: Optional[AuthorizationRecord], method: str = "GET") -> None:
+        """
+        Hard security gate: raises AuthorizationError if auth is missing, expired,
+        or URL violates scope boundaries.
+        """
+        if not auth:
+            raise AuthorizationError("Runtime validation blocked: No authorization record provided.")
+
+        # Method check
+        if method.upper() in ["POST", "PUT", "DELETE", "PATCH"] and not auth.scope.allow_state_changing_methods:
+            raise AuthorizationError(f"State-changing method '{method}' is forbidden under current scope.")
+
+        valid, reason = cls.validate_url(url, auth.scope)
+        if not valid:
+            raise AuthorizationError(f"Runtime validation blocked: {reason}")
+
+    @classmethod
+    def write_artifacts(cls, run_dir: Path, auth: AuthorizationRecord) -> Tuple[Path, Path]:
+        """
+        Emits standard scope.json and authorization.md into the run folder.
+        """
+        run_dir.mkdir(parents=True, exist_ok=True)
+        scope_file = run_dir / "scope.json"
+        auth_file = run_dir / "authorization.md"
+
+        # 1. Write scope.json
+        with open(scope_file, "w", encoding="utf-8") as f:
+            json.dump(auth.to_dict(), f, indent=2)
+
+        # 2. Write authorization.md
+        md_content = f"""# TorusGuard v0.7.0 Runtime Authorization Document
+
+**Authorization ID:** `{auth.authorization_id}`  
+**Target Application:** `{auth.target_name}`  
+**Authorized By:** `{auth.authorized_by}`  
+**Authorization Type:** `{auth.authorization_type}`  
+**Created At:** `{auth.created_at}`  
+
+---
+
+## 🔒 Scope Boundaries & Permitted Constraints
+
+| Parameter | Allowed Value |
+|---|---|
+| **Target Hosts** | `{", ".join(auth.scope.target_hosts)}` |
+| **Allowed Path Prefixes** | `{", ".join(auth.scope.allowed_path_prefixes)}` |
+| **Forbidden Paths** | `{", ".join(auth.scope.forbidden_paths)}` |
+| **Active Window** | `{auth.scope.valid_from}` ➔ `{auth.scope.valid_until}` |
+| **Max Navigation Depth** | `{auth.scope.max_depth}` levels |
+| **Max Request Budget** | `{auth.scope.max_requests}` requests |
+| **State-Changing Methods** | `{"Allowed" if auth.scope.allow_state_changing_methods else "Forbidden (Read-only GET/HEAD only)"}` |
+| **Approved Issue Classes** | `{", ".join(auth.scope.allowed_issue_classes or [])}` |
+
+---
+
+## ⚖️ Legal & Governance Statement
+This authorization represents verifiable consent by `{auth.authorized_by}` to perform non-destructive, bounded runtime validation against the specified target hosts. Destructive testing, denial of service, memory corruption, and automated credential stuffing are strictly prohibited.
+"""
+        with open(auth_file, "w", encoding="utf-8") as f:
+            f.write(md_content)
+
+        return scope_file, auth_file