torusguard 2.0.0-alpha → 2.1.1

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

@@ -0,0 +1,189 @@
+"""
+TorusGuard v6 SARIF v2.1.0 Exporter
+Emits standard SARIF-compatible JSON reports for CI/CD, GitHub Security Code Scanning, and SIEM tool integration.
+"""
+
+import json
+from typing import List, Dict, Any, Optional, Tuple
+from pathlib import Path
+
+
+class SarifExporter:
+    """
+    Transforms TorusGuard findings and clusters into standard SARIF v2.1.0 format.
+    """
+
+    SARIF_VERSION = "2.1.0"
+    SARIF_SCHEMA = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json"
+
+    @staticmethod
+    def map_severity_to_level(severity: str) -> str:
+        """Maps TorusGuard SeverityLevel to standard SARIF result level."""
+        if severity in ["Critical", "High"]:
+            return "error"
+        elif severity in ["Low", "Informational"]:
+            return "note"
+        return "warning"
+
+    @staticmethod
+    def _build_rule_entry(rule_id: str, title: str, sarif_level: str, category: str = "security") -> Dict[str, Any]:
+        """Constructs a SARIF reportingDescriptor object for a rule."""
+        return {
+            "id": rule_id,
+            "name": rule_id.replace("-", "_"),
+            "shortDescription": {"text": title},
+            "fullDescription": {"text": f"TorusGuard Rule {rule_id}: {title}"},
+            "defaultConfiguration": {"level": sarif_level},
+            "help": {"text": f"Read documentation for {rule_id} at https://github.com/githubmofo/TorusGuard"},
+            "properties": {"category": category}
+        }
+
+    @classmethod
+    def _build_result_entry(
+        cls, f: Dict[str, Any], rule_index: int, sarif_level: str, analysis_category: str
+    ) -> Dict[str, Any]:
+        """Constructs a single SARIF result item with fingerprints and location."""
+        rule_id = f.get("rule_id", "TG-GENERIC")
+        finding_id = f.get("finding_id", "")
+        title = f.get("title", rule_id)
+        confidence_score = f.get("confidence_score", 80)
+        confidence_band = f.get("confidence_band", "High Confidence")
+        cluster_id = f.get("cluster_id", "")
+
+        target = f.get("target", {})
+        file_path = target.get("file_path", "unknown").replace("\\", "/")
+        start_line = max(1, target.get("line_start", 1))
+        end_line = max(start_line, target.get("line_end", start_line))
+        evidence_snippet = f.get("evidence", {}).get("code_snippet", "")
+        fingerprint = f.get("fingerprint_id", finding_id)
+
+        return {
+            "ruleId": rule_id,
+            "ruleIndex": rule_index,
+            "level": sarif_level,
+            "message": {
+                "text": f"[{rule_id}] {title} (Confidence: {confidence_score}/100 - {confidence_band})"
+            },
+            "locations": [
+                {
+                    "physicalLocation": {
+                        "artifactLocation": {
+                            "uri": file_path,
+                            "uriBaseId": "%SRCROOT%"
+                        },
+                        "region": {
+                            "startLine": start_line,
+                            "endLine": end_line,
+                            "snippet": {"text": evidence_snippet}
+                        }
+                    }
+                }
+            ],
+            "partialFingerprints": {
+                "primaryLocationLineHash": fingerprint[:16] if fingerprint else "0" * 16,
+                "torusguard/v6/identity": fingerprint
+            },
+            "fingerprints": {
+                "torusguard/v6/stable_identity": fingerprint
+            },
+            "properties": {
+                "finding_id": finding_id,
+                "confidence_score": confidence_score,
+                "confidence_band": confidence_band,
+                "cluster_id": cluster_id,
+                "recheck_status": f.get("recheck_status", "Unrechecked"),
+                "runtime_exploitability": f.get("runtime_exploitability", "Not Tested"),
+                "tags": ["security", "governed-remediation", cluster_id, analysis_category]
+            }
+        }
+
+    @classmethod
+    def generate_sarif(
+        cls,
+        findings: List[Dict[str, Any]],
+        clusters: Optional[List[Dict[str, Any]]] = None,
+        tool_version: str = "0.7.0",
+        analysis_category: str = "torusguard/static",
+    ) -> Dict[str, Any]:
+        """
+        Builds a complete SARIF log dict supporting multi-analysis category partitioning.
+        """
+        rules_map: Dict[str, Dict[str, Any]] = {}
+        results: List[Dict[str, Any]] = []
+
+        for f in findings:
+            rule_id = f.get("rule_id", "TG-GENERIC")
+            title = f.get("title", rule_id)
+            severity = f.get("severity", "High")
+            sarif_level = cls.map_severity_to_level(severity)
+
+            if rule_id not in rules_map:
+                rules_map[rule_id] = cls._build_rule_entry(
+                    rule_id, title, sarif_level, category=f.get("category", "security")
+                )
+
+            rule_index = list(rules_map.keys()).index(rule_id)
+            result_obj = cls._build_result_entry(f, rule_index, sarif_level, analysis_category)
+            results.append(result_obj)
+
+        sarif_payload = {
+            "$schema": cls.SARIF_SCHEMA,
+            "version": cls.SARIF_VERSION,
+            "runs": [
+                {
+                    "tool": {
+                        "driver": {
+                            "name": "TorusGuard",
+                            "semanticVersion": tool_version,
+                            "informationUri": "https://github.com/githubmofo/TorusGuard",
+                            "rules": list(rules_map.values()),
+                        }
+                    },
+                    "automationDetails": {
+                        "id": f"{analysis_category}/"
+                    },
+                    "results": results
+                }
+            ]
+        }
+
+        return sarif_payload
+
+    @classmethod
+    def validate_github_sarif(cls, sarif_dict: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """
+        Validates that a SARIF payload meets GitHub Code Scanning upload constraints:
+        - $schema is present
+        - version is 2.1.0
+        - runs contains at least one driver with rules
+        - results have valid ruleIds, locations with artifactLocation.uri, and partialFingerprints
+        """
+        errors = []
+        if sarif_dict.get("version") != "2.1.0":
+            errors.append("SARIF version must be 2.1.0")
+        if not sarif_dict.get("$schema"):
+            errors.append("SARIF missing $schema header")
+        
+        runs = sarif_dict.get("runs", [])
+        if not runs:
+            errors.append("SARIF must contain at least one run")
+            return False, errors
+
+        driver = runs[0].get("tool", {}).get("driver", {})
+        if not driver.get("name"):
+            errors.append("Tool driver must specify name")
+
+        results = runs[0].get("results", [])
+        for idx, res in enumerate(results):
+            if not res.get("ruleId"):
+                errors.append(f"Result {idx} missing ruleId")
+            if not res.get("locations"):
+                errors.append(f"Result {idx} missing locations")
+            else:
+                uri = res["locations"][0].get("physicalLocation", {}).get("artifactLocation", {}).get("uri")
+                if not uri:
+                    errors.append(f"Result {idx} missing artifactLocation uri")
+            if "partialFingerprints" not in res:
+                errors.append(f"Result {idx} missing partialFingerprints for GitHub deduplication")
+
+        return len(errors) == 0, errors

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

@@ -0,0 +1,184 @@
+"""
+TorusGuard v6.2 Modern Stack Profiler & Version Family Detector
+Analyzes project manifests, code syntax, and dependency configurations to detect
+framework version families (Django 5.x/4.x, FastAPI/Pydantic v2, SQLAlchemy 2.0, Next.js 14+),
+async paradigms, container/workflow setups, and modern configuration patterns.
+"""
+
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+from typing import Dict, List, Any, Optional, Set
+import re
+import json
+
+
+@dataclass
+class StackProfile:
+    primary_language: str = "Python"
+    framework: str = "Unknown"
+    version_family: str = "Modern"
+    is_async: bool = False
+    orm_layer: str = "None"
+    orm_version_family: str = "2.0+"
+    config_loader: str = "Standard"
+    dependency_manager: str = "pip"
+    container_engine: Optional[str] = None
+    ci_platform: Optional[str] = None
+    frontend_framework: Optional[str] = None
+    detected_features: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+class StackProfiler:
+    """
+    Inspects repository files to determine comprehensive modern stack profile.
+    """
+
+    @classmethod
+    def profile_repository(cls, repo_path: Path) -> StackProfile:
+        profile = StackProfile()
+        detected_features = []
+
+        if not repo_path.exists():
+            return profile
+
+        # Collect files
+        all_files: List[Path] = []
+        try:
+            for p in repo_path.rglob("*"):
+                if p.is_file() and not any(part.startswith(".") and part != ".github" for part in p.parts):
+                    all_files.append(p)
+        except Exception:
+            pass
+
+        file_names = {f.name for f in all_files}
+        file_paths_str = [str(f.relative_to(repo_path)).replace("\\", "/") for f in all_files]
+
+        # 1. Dependency Manager & Ecosystem Detection
+        if "uv.lock" in file_names:
+            profile.dependency_manager = "uv"
+            detected_features.append("uv (Astral) fast package manager")
+        elif "poetry.lock" in file_names:
+            profile.dependency_manager = "poetry"
+            detected_features.append("Poetry packaging")
+        elif "Pipfile.lock" in file_names:
+            profile.dependency_manager = "pipenv"
+        elif "pnpm-lock.yaml" in file_names:
+            profile.dependency_manager = "pnpm"
+        elif "package-lock.json" in file_names:
+            profile.dependency_manager = "npm"
+        elif "yarn.lock" in file_names:
+            profile.dependency_manager = "yarn"
+        elif "go.mod" in file_names:
+            profile.primary_language = "Go"
+            profile.dependency_manager = "go modules"
+            detected_features.append("Go Modules package ecosystem")
+        elif "Cargo.toml" in file_names:
+            profile.primary_language = "Rust"
+            profile.dependency_manager = "cargo"
+            detected_features.append("Cargo package manager (Rust)")
+        elif "pom.xml" in file_names:
+            profile.primary_language = "Java"
+            profile.dependency_manager = "maven"
+            detected_features.append("Maven project layout")
+        elif "build.gradle" in file_names or "build.gradle.kts" in file_names:
+            profile.primary_language = "Kotlin" if "build.gradle.kts" in file_names else "Java"
+            profile.dependency_manager = "gradle"
+            detected_features.append("Gradle build tool")
+        elif any(f.endswith(".csproj") for f in file_names):
+            profile.primary_language = "C#"
+            profile.dependency_manager = "dotnet / nuget"
+            detected_features.append(".NET / C# project ecosystem")
+        elif "composer.json" in file_names:
+            profile.primary_language = "PHP"
+            profile.dependency_manager = "composer"
+            detected_features.append("Composer package manager (PHP)")
+        elif "Gemfile" in file_names:
+            profile.primary_language = "Ruby"
+            profile.dependency_manager = "bundler"
+            detected_features.append("Bundler package manager (Ruby)")
+        elif "pyproject.toml" in file_names:
+            profile.dependency_manager = "pyproject.toml (PEP 621)"
+
+        # 2. Container & CI Platform
+        if any("Dockerfile" in name or "Containerfile" in name for name in file_names):
+            profile.container_engine = "Docker / OCI Container"
+            detected_features.append("Containerized deployment (Dockerfile)")
+        if any(p.startswith(".github/workflows/") for p in file_paths_str):
+            profile.ci_platform = "GitHub Actions"
+            detected_features.append("GitHub Actions CI/CD workflows")
+
+        # 3. Source Code Inspection
+        py_files = [f for f in all_files if f.suffix in [".py", ".pyi"]]
+        ts_files = [f for f in all_files if f.suffix in [".ts", ".tsx", ".js", ".jsx"]]
+
+        py_content_sample = ""
+        for pf in py_files[:20]:
+            try:
+                py_content_sample += pf.read_text(encoding="utf-8", errors="ignore") + "\n"
+            except Exception:
+                pass
+
+        ts_content_sample = ""
+        for tf in ts_files[:20]:
+            try:
+                ts_content_sample += tf.read_text(encoding="utf-8", errors="ignore") + "\n"
+            except Exception:
+                pass
+
+        # Check async paradigm
+        if "async def " in py_content_sample or "await " in py_content_sample:
+            profile.is_async = True
+            detected_features.append("Async / Await Coroutines")
+
+        # Framework & Version Family Detection
+        if "from fastapi" in py_content_sample or "import fastapi" in py_content_sample:
+            profile.framework = "FastAPI"
+            if "Annotated[" in py_content_sample or "model_validator" in py_content_sample or "pydantic_settings" in py_content_sample:
+                profile.version_family = "FastAPI 0.100+ (Pydantic v2)"
+                detected_features.append("Pydantic v2 Typed Validation & Annotated Dependencies")
+            else:
+                profile.version_family = "FastAPI 0.9x (Legacy)"
+
+        elif "django" in py_content_sample or "DJANGO_SETTINGS_MODULE" in py_content_sample:
+            profile.framework = "Django"
+            if "aget(" in py_content_sample or "asgiref" in py_content_sample or "async def " in py_content_sample:
+                profile.version_family = "Django 5.x (Async Native)"
+                detected_features.append("Django 5.x Async ORM & Views")
+            else:
+                profile.version_family = "Django 4.x / Standard"
+
+        elif "from flask" in py_content_sample or "import flask" in py_content_sample:
+            profile.framework = "Flask"
+            profile.version_family = "Flask 3.x"
+
+        # ORM Layer
+        if "sqlalchemy" in py_content_sample:
+            profile.orm_layer = "SQLAlchemy"
+            if "select(" in py_content_sample or "AsyncSession" in py_content_sample or "mapped_column" in py_content_sample:
+                profile.orm_version_family = "SQLAlchemy 2.0+ (Modern 2.0 Syntax)"
+                detected_features.append("SQLAlchemy 2.0 select() queries & async sessions")
+            else:
+                profile.orm_version_family = "SQLAlchemy 1.4 (Legacy Query API)"
+        elif profile.framework == "Django":
+            profile.orm_layer = "Django ORM"
+            profile.orm_version_family = "Django Model Manager"
+
+        # Frontend Framework
+        if '"next"' in ts_content_sample or "'next'" in ts_content_sample or "use server" in ts_content_sample:
+            profile.frontend_framework = "Next.js 14+ (App Router)"
+            detected_features.append("Next.js App Router & Server Actions")
+        elif "react" in ts_content_sample:
+            profile.frontend_framework = "React"
+
+        # Configuration Loading
+        if "pydantic_settings" in py_content_sample or "BaseSettings" in py_content_sample:
+            profile.config_loader = "pydantic-settings (Type-Safe Env)"
+            detected_features.append("pydantic-settings environment validation")
+        elif "os.getenv" in py_content_sample or "os.environ" in py_content_sample:
+            profile.config_loader = "os.environ"
+
+        profile.detected_features = detected_features
+        return profile

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

@@ -0,0 +1,91 @@
+"""
+TorusGuard Symbol Table Engine
+Per-file symbol resolution for tracking variable definitions, scopes, types,
+and import aliases across language scopes.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Any
+
+
+@dataclass
+class VariableInfo:
+    name: str
+    defined_line: int
+    scope_name: str = "global"
+    assigned_expression: str = ""
+    is_tainted: bool = False
+    inferred_type: str = "unknown"
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+
+class SymbolTable:
+    """Tracks variable definitions, scopes, and types within a single file."""
+
+    def __init__(self, file_path: str = ""):
+        self.file_path = file_path
+        self.variables: Dict[str, List[VariableInfo]] = {}
+        self.import_aliases: Dict[str, str] = {}
+        self.function_defs: Dict[str, int] = {}
+
+    def add_variable(
+        self,
+        name: str,
+        line: int,
+        scope: str = "global",
+        expression: str = "",
+        is_tainted: bool = False,
+        inferred_type: str = "unknown"
+    ) -> VariableInfo:
+        var_info = VariableInfo(
+            name=name,
+            defined_line=line,
+            scope_name=scope,
+            assigned_expression=expression,
+            is_tainted=is_tainted,
+            inferred_type=inferred_type
+        )
+        if name not in self.variables:
+            self.variables[name] = []
+        self.variables[name].append(var_info)
+        return var_info
+
+    def resolve_variable(self, name: str, at_line: int) -> Optional[VariableInfo]:
+        """
+        Given a variable name and current line, returns its most recent definition
+        preceding or at that line.
+        """
+        defs = self.variables.get(name, [])
+        candidate = None
+        for d in defs:
+            if d.defined_line <= at_line:
+                if candidate is None or d.defined_line > candidate.defined_line:
+                    candidate = d
+        return candidate
+
+    def add_import_alias(self, alias: str, canonical_name: str) -> None:
+        """Register an import alias (e.g. `from flask import request as req`)."""
+        self.import_aliases[alias] = canonical_name
+
+    def get_import_alias(self, alias: str) -> Optional[str]:
+        """Resolve an alias to its canonical symbol or module."""
+        return self.import_aliases.get(alias)
+
+    def mark_tainted(self, name: str, at_line: int) -> None:
+        var_info = self.resolve_variable(name, at_line)
+        if var_info:
+            var_info.is_tainted = True
+        else:
+            self.add_variable(name=name, line=at_line, is_tainted=True)
+
+    def is_tainted(self, name: str, at_line: int) -> bool:
+        var_info = self.resolve_variable(name, at_line)
+        return var_info.is_tainted if var_info else False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "file_path": self.file_path,
+            "variables": {k: [v.defined_line for v in vs] for k, vs in self.variables.items()},
+            "import_aliases": self.import_aliases,
+            "functions": self.function_defs
+        }

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

@@ -0,0 +1,133 @@
+"""
+TorusGuard Taint Engine — Core Taint Models & Propagation Dataclasses
+Defines source, sink, sanitizer entities and dataflow propagation primitives.
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import List, Dict, Any, Optional, Set
+
+
+@dataclass
+class TaintSource:
+    pattern: str
+    framework: str
+    label: str
+    category: str
+    language: str
+    line_number: int = 0
+    file_path: str = ""
+    variable_name: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class TaintSink:
+    pattern: str
+    category: str
+    rule_id: str
+    severity: str
+    language: str
+    line_number: int = 0
+    file_path: str = ""
+    argument_name: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class TaintSanitizer:
+    pattern: str
+    cleans: List[str]
+    language: str
+    line_number: int = 0
+    file_path: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class TaintNode:
+    variable_name: str
+    file_path: str
+    line_number: int
+    node_type: str  # "source" | "transform" | "sink" | "sanitizer"
+    expression: str = ""
+    pattern: str = ""
+    category: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def node_id(self) -> str:
+        return f"{self.file_path}:{self.line_number}:{self.variable_name}:{self.node_type}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class TaintEdge:
+    from_node: TaintNode
+    to_node: TaintNode
+    edge_type: str  # "assignment" | "argument" | "return" | "attribute" | "call"
+    line_number: int = 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "from_node": self.from_node.node_id(),
+            "to_node": self.to_node.node_id(),
+            "edge_type": self.edge_type,
+            "line_number": self.line_number,
+        }
+
+
+@dataclass
+class TaintPath:
+    source: TaintNode
+    sink: TaintNode
+    path: List[TaintNode]
+    is_sanitized: bool = False
+    sanitizers_found: List[TaintNode] = field(default_factory=list)
+    confidence_penalty: int = 0
+
+    @property
+    def depth(self) -> int:
+        return max(0, len(self.path) - 1)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "source": self.source.to_dict(),
+            "sink": self.sink.to_dict(),
+            "depth": self.depth,
+            "is_sanitized": self.is_sanitized,
+            "sanitizers_found": [s.to_dict() for s in self.sanitizers_found],
+            "path_nodes": [n.to_dict() for n in self.path],
+        }
+
+
+class TaintPropagator:
+    """
+    Evaluates statement-level and expression-level taint transfer.
+    Determines if assignment, function call, or operation propagates taint
+    from RHS variables to LHS target.
+    """
+
+    @staticmethod
+    def propagates_taint(source_vars: Set[str], expression: str) -> bool:
+        """Checks if any currently tainted variable appears in the expression."""
+        if not source_vars or not expression:
+            return False
+        import re
+        tokens = set(re.findall(r"\b[A-Za-z_][A-Za-z0-9_]*\b", expression))
+        return bool(tokens.intersection(source_vars))
+
+    @staticmethod
+    def is_sanitizer_expression(expression: str, sanitizers: List[Dict[str, Any]], category: str) -> Optional[Dict[str, Any]]:
+        """Returns the matching sanitizer if the expression applies a known sanitizer for the category."""
+        for s in sanitizers:
+            if s["pattern"] in expression:
+                if not category or category in s.get("cleans", []):
+                    return s
+        return None