torusguard 0.9.2

package/.torusguard/schemas/finding.schema.json

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/finding.schema.json",
+  "title": "TorusGuardCanonicalFinding",
+  "description": "Canonical normalized finding object schema for TorusGuard v0.5.1 with provenance and auditable confidence scoring.",
+  "type": "object",
+  "required": [
+    "finding_id",
+    "rule_id",
+    "title",
+    "category",
+    "severity",
+    "confidence",
+    "status",
+    "affected_component",
+    "evidence",
+    "provenance",
+    "reproduction_method",
+    "remediation",
+    "retest_result",
+    "timestamps"
+  ],
+  "properties": {
+    "finding_id": {
+      "type": "string",
+      "pattern": "^TG-FIND-[0-9]{4}-[a-f0-9]{4,12}$",
+      "description": "Unique canonical identifier for this finding instance."
+    },
+    "rule_id": {
+      "type": "string",
+      "pattern": "^TG-[A-Z0-9]+-[0-9]{3}$",
+      "description": "Canonical TorusGuard Rule ID (e.g. TG-AUTH-007, TG-SEC-001)."
+    },
+    "title": {
+      "type": "string",
+      "description": "Concise, human-readable finding title."
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "authentication-authorization",
+        "input-validation-encoding",
+        "data-access-orm",
+        "file-upload-handling",
+        "secrets-configuration",
+        "dependency-supply-chain",
+        "network-ssrf-boundaries",
+        "business-logic-rate-limiting",
+        "client-cache-platform"
+      ],
+      "description": "Normalized lifecycle taxonomy category."
+    },
+    "severity": {
+      "type": "object",
+      "required": ["level", "rationale", "rubric_justification"],
+      "properties": {
+        "level": {
+          "type": "string",
+          "enum": ["Critical", "High", "Medium", "Low", "Informational"]
+        },
+        "rationale": {
+          "type": "string",
+          "description": "Justification for assigned severity level."
+        },
+        "rubric_justification": {
+          "type": "string",
+          "description": "Explicit reason why this finding is not a higher or lower severity."
+        }
+      }
+    },
+    "confidence": {
+      "$ref": "confidence.schema.json"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "Confirmed",
+        "High Confidence",
+        "Medium Confidence",
+        "Low Confidence",
+        "Unconfirmed",
+        "Needs Review",
+        "Remediated",
+        "Verified Fixed"
+      ],
+      "description": "Standardized operational verification status."
+    },
+    "affected_component": {
+      "type": "object",
+      "required": ["component_name", "target_path"],
+      "properties": {
+        "component_name": { "type": "string" },
+        "target_path": { "type": "string" },
+        "start_line": { "type": "integer" },
+        "end_line": { "type": "integer" },
+        "symbol": { "type": "string" }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "evidence.schema.json" }
+    },
+    "provenance": {
+      "$ref": "provenance.schema.json"
+    },
+    "reproduction_method": {
+      "type": "object",
+      "required": ["step_by_step", "deterministic"],
+      "properties": {
+        "step_by_step": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "test_command": { "type": "string" },
+        "deterministic": { "type": "boolean" },
+        "expected_failure_response": { "type": "string" }
+      }
+    },
+    "remediation": {
+      "$ref": "remediation.schema.json"
+    },
+    "retest_result": {
+      "$ref": "retest.schema.json"
+    },
+    "requirement_reference": {
+      "type": "object",
+      "properties": {
+        "asvs_v4": { "type": "string" },
+        "nist_ssdf": { "type": "string" },
+        "owasp_top10": { "type": "string" }
+      }
+    },
+    "cwe": {
+      "type": "string",
+      "pattern": "^CWE-[0-9]{1,5}$"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["discovered_at", "updated_at"],
+      "properties": {
+        "discovered_at": { "type": "string", "format": "date-time" },
+        "verified_at": { "type": "string", "format": "date-time" },
+        "remediated_at": { "type": "string", "format": "date-time" },
+        "retested_at": { "type": "string", "format": "date-time" },
+        "updated_at": { "type": "string", "format": "date-time" }
+      }
+    },
+    "notes": {
+      "type": "object",
+      "required": ["raw_facts_summary", "ai_interpretation"],
+      "properties": {
+        "raw_facts_summary": {
+          "type": "string",
+          "description": "Objective, unembellished summary of verified code facts."
+        },
+        "ai_interpretation": {
+          "type": "string",
+          "description": "AI-generated risk analysis and contextual reasoning."
+        }
+      }
+    }
+  }
+}

package/.torusguard/schemas/provenance.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/provenance.schema.json",
+  "title": "TorusGuardProvenanceChain",
+  "description": "Structured provenance chain tracking discovery and decision path for TorusGuard v0.5.1 findings.",
+  "type": "object",
+  "required": [
+    "discovery_module",
+    "triggering_input",
+    "evidence_collected",
+    "decision_path",
+    "verification_step"
+  ],
+  "properties": {
+    "discovery_module": {
+      "type": "string",
+      "description": "Module or rule that initiated the detection (e.g. rules/authorization/TG-AUTH-007)."
+    },
+    "triggering_input": {
+      "type": "string",
+      "description": "The specific input, AST node, manifest line, or configuration key that triggered detection."
+    },
+    "evidence_collected": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of evidence identifiers or file locations gathered during discovery."
+    },
+    "decision_path": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Ordered sequence of logical evaluation steps leading to the finding classification."
+    },
+    "verification_step": {
+      "type": "string",
+      "description": "Verification method used to confirm or refute the finding."
+    },
+    "agent_environment": {
+      "type": "string",
+      "description": "Runtime context (e.g. TorusGuard Engine v0.5.1 on Python 3.11)."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/.torusguard/schemas/remediation.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/remediation.schema.json",
+  "title": "TorusGuardRemediation",
+  "description": "Standard remediation guidance schema for TorusGuard v0.5.0 findings.",
+  "type": "object",
+  "required": [
+    "problem_statement",
+    "risk_explanation",
+    "recommended_fix",
+    "framework_pattern",
+    "verification_method",
+    "residual_risk_notes"
+  ],
+  "properties": {
+    "problem_statement": {
+      "type": "string",
+      "description": "Direct, single-sentence summary of the flaw in the current implementation."
+    },
+    "risk_explanation": {
+      "type": "string",
+      "description": "Explains how an adversary can abuse this pattern and the concrete security impact."
+    },
+    "recommended_fix": {
+      "type": "string",
+      "description": "Clear, prescriptive step-by-step instructions to remediate the vulnerability."
+    },
+    "framework_pattern": {
+      "type": "object",
+      "required": ["framework", "unsafe_snippet", "safe_snippet"],
+      "properties": {
+        "framework": {
+          "type": "string",
+          "description": "Target framework or ecosystem (e.g. Django, DRF, FastAPI, Flask, SQLAlchemy, Express, Next.js)."
+        },
+        "unsafe_snippet": {
+          "type": "string",
+          "description": "Illustrative code demonstrating the unsafe pattern."
+        },
+        "safe_snippet": {
+          "type": "string",
+          "description": "Framework-native, production-grade hardened code snippet."
+        },
+        "least_invasive": {
+          "type": "boolean",
+          "description": "True if the remediation preserves existing architectural patterns without unnecessary rewrites."
+        }
+      }
+    },
+    "verification_method": {
+      "type": "string",
+      "description": "How a human engineer or automated test can verify that the fix was applied successfully."
+    },
+    "residual_risk_notes": {
+      "type": "string",
+      "description": "Known edge cases, out-of-band requirements (e.g. cloud IAM, reverse proxy headers), or operational trade-offs."
+    }
+  }
+}

package/.torusguard/schemas/retest.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://torusguard.dev/schemas/retest.schema.json",
+  "title": "TorusGuardRetestRecord",
+  "description": "Schema for explicit retest execution, fix verification, and closure status in TorusGuard v0.5.1.",
+  "type": "object",
+  "required": [
+    "retest_performed",
+    "closure_status"
+  ],
+  "properties": {
+    "retest_performed": {
+      "type": "boolean",
+      "description": "True if an automated or manual retest has been executed on the post-fix codebase."
+    },
+    "retest_timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "fix_applied": {
+      "type": "string",
+      "description": "Summary of the code patch or configuration change applied."
+    },
+    "retest_method": {
+      "type": "string",
+      "description": "Method used to verify resolution (e.g. differential static recheck, automated unit test)."
+    },
+    "retest_evidence_hash": {
+      "type": "string",
+      "description": "SHA-256 hash of the modified source file confirming post-fix state."
+    },
+    "closure_status": {
+      "type": "string",
+      "enum": [
+        "Unconfirmed",
+        "Open",
+        "Remediated",
+        "Verified Fixed",
+        "Fix Incomplete",
+        "Suppressed - Accepted Risk"
+      ],
+      "description": "Final verified operational status of the finding."
+    },
+    "residual_risk": {
+      "type": "string",
+      "description": "Any residual operational or architectural risk remaining after the fix."
+    },
+    "verifier_notes": {
+      "type": "string",
+      "description": "Human or AI verifier notes detailing retest observations."
+    }
+  }
+}

package/.torusguard/schemas/runtime-evidence.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "TorusGuardRuntimeEvidence",
+  "description": "Schema for TorusGuard v0.7.0 captured runtime HTTP/browser evidence.",
+  "type": "object",
+  "required": [
+    "evidence_id",
+    "finding_id",
+    "timestamp",
+    "method",
+    "url",
+    "status_code",
+    "exploitability_status"
+  ],
+  "properties": {
+    "evidence_id": {
+      "type": "string"
+    },
+    "finding_id": {
+      "type": "string"
+    },
+    "cluster_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "method": {
+      "type": "string",
+      "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]
+    },
+    "url": {
+      "type": "string"
+    },
+    "path": {
+      "type": "string"
+    },
+    "status_code": {
+      "type": "integer"
+    },
+    "request_headers": {
+      "type": "object"
+    },
+    "response_headers": {
+      "type": "object"
+    },
+    "response_body_snippet": {
+      "type": "string"
+    },
+    "exploitability_status": {
+      "type": "string",
+      "enum": [
+        "Runtime Confirmed",
+        "Runtime Likely",
+        "Needs Manual Review",
+        "Not Reproducible in Scope",
+        "Blocked by Environment / Controls"
+      ]
+    },
+    "reproducible": {
+      "type": "boolean"
+    },
+    "route_context": {
+      "type": "string"
+    },
+    "reviewer_notes": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

package/.torusguard/scripts/diff_guard.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""
+TorusGuard Content-Aware Diff Line Scanner (v0.9.3)
+Evaluates unified diff patches against security invariants before harden or apply.
+Pure Python 3.10+ standard library (zero external dependencies).
+"""
+
+import sys
+import os
+import re
+import json
+import argparse
+from pathlib import Path
+from typing import Dict, List, Any, Optional
+
+BYPASS_PATTERNS = [
+    (re.compile(r'(?:#|//)\s*(?:TODO\s*:?\s*)?(?:bypass|skip|disable)[_\s]*(?:auth|security|check|guard|filter|csrf|tenant)', re.IGNORECASE), "Suspicious authentication or security check bypass comment"),
+    (re.compile(r'\bverify\s*=\s*False\b'), "Disabled TLS certificate verification (verify=False)"),
+    (re.compile(r'\b(?:skip_auth|bypass_auth|disable_auth|allow_all|permit_all)\s*=\s*True\b', re.IGNORECASE), "Explicit security bypass flag enabled"),
+    (re.compile(r'@(?:csrf_exempt|allow_anonymous|disable_token_check)\b'), "Decorator disabling route-level security or CSRF protection"),
+    (re.compile(r'\bCORS_ALLOW_ALL_ORIGINS\s*=\s*True\b'), "Wildcard CORS origin enabled in patch"),
+    (re.compile(r'(?:#|//)\s*nosec\b', re.IGNORECASE), "Suppression comment (nosec) hiding potential vulnerability")
+]
+
+SECRET_PATTERNS = [
+    (re.compile(r'\b(?:sk_live|ak_live)_[0-9a-zA-Z]{20,}\b'), "Live payment or cloud API secret key"),
+    (re.compile(r'\bgh[pousr]_[0-9a-zA-Z]{36}\b'), "GitHub personal access token"),
+    (re.compile(r'\beyJ[A-Za-z0-9-_=]+\.[A-Za-z0-9-_=]+\.[A-Za-z0-9-_.+/=]+\b'), "Hardcoded JSON Web Token (JWT) string"),
+    (re.compile(r'-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----'), "Hardcoded private key block"),
+    (re.compile(r'(?:password|secret|api_key|access_token)\s*=\s*["\'][A-Za-z0-9@#$%^&+=_\-]{8,}["\']', re.IGNORECASE), "Hardcoded credential or API secret string")
+]
+
+TENANT_FILTER_PATTERNS = [
+    re.compile(r'\.filter\([^)]*\btenant\s*='),
+    re.compile(r'\.filter_by\([^)]*\btenant\s*='),
+    re.compile(r'\bwhere\s+tenant_id\s*='),
+    re.compile(r'\btenant_id\s*==?')
+]
+
+
+def audit_diff(diff_content: str) -> Dict[str, Any]:
+    """
+    Parses a unified diff and returns detected violations.
+    """
+    lines = diff_content.splitlines()
+    violations: List[Dict[str, Any]] = []
+    
+    current_file = "unknown"
+    current_line = 0
+    
+    additions: List[tuple[int, str]] = []
+    deletions: List[tuple[int, str]] = []
+
+    for line_idx, line in enumerate(lines, 1):
+        if line.startswith('+++ b/'):
+            current_file = line[6:].strip()
+            continue
+        elif line.startswith('--- a/'):
+            continue
+        elif line.startswith('@@'):
+            # Parse line number e.g. @@ -10,5 +12,6 @@
+            match = re.search(r'\+(\d+)', line)
+            if match:
+                current_line = int(match.group(1)) - 1
+            continue
+
+        if line.startswith('+') and not line.startswith('+++'):
+            current_line += 1
+            added_content = line[1:]
+            additions.append((current_line, added_content))
+            
+            # Check bypass patterns
+            for pat, desc in BYPASS_PATTERNS:
+                if pat.search(added_content):
+                    violations.append({
+                        "rule_id": "TG-DIFF-001",
+                        "category": "Bypass Sink",
+                        "severity": "CRITICAL",
+                        "file": current_file,
+                        "line": current_line,
+                        "content": added_content.strip(),
+                        "description": desc
+                    })
+                    
+            # Check secret ingestion
+            for pat, desc in SECRET_PATTERNS:
+                if pat.search(added_content):
+                    violations.append({
+                        "rule_id": "TG-DIFF-002",
+                        "category": "Secret Ingestion",
+                        "severity": "CRITICAL",
+                        "file": current_file,
+                        "line": current_line,
+                        "content": "[REDACTED_POTENTIAL_SECRET]",
+                        "description": desc
+                    })
+
+        elif line.startswith('-') and not line.startswith('---'):
+            deleted_content = line[1:]
+            deletions.append((line_idx, deleted_content))
+
+    # Check for tenant filter deletion without replacement
+    for del_idx, del_line in deletions:
+        for t_pat in TENANT_FILTER_PATTERNS:
+            if t_pat.search(del_line):
+                # Verify if an equivalent tenant filter exists in additions
+                replaced = any(t_pat.search(add_line) for _, add_line in additions)
+                if not replaced:
+                    violations.append({
+                        "rule_id": "TG-DIFF-003",
+                        "category": "Tenant Filter Removal",
+                        "severity": "HIGH",
+                        "file": current_file,
+                        "line": del_idx,
+                        "content": del_line.strip(),
+                        "description": "Tenant isolation filter was removed without being restored in additions"
+                    })
+
+    status = "PASSED" if not violations else "BLOCKED"
+    return {
+        "status": status,
+        "files_inspected": list(set(v["file"] for v in violations)) if violations else [current_file],
+        "additions_count": len(additions),
+        "deletions_count": len(deletions),
+        "total_violations": len(violations),
+        "violations": violations
+    }
+
+
+def audit_diff_file(file_path: str) -> Dict[str, Any]:
+    path = Path(file_path)
+    if not path.is_file():
+        return {
+            "status": "ERROR",
+            "error": f"File not found: {file_path}",
+            "violations": []
+        }
+    content = path.read_text(encoding="utf-8", errors="replace")
+    return audit_diff(content)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="TorusGuard Unified Diff Security Scanner")
+    parser.add_argument("diff_path", nargs="?", help="Path to unified diff file (or read stdin if omitted)")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    args = parser.parse_args()
+
+    if args.diff_path:
+        res = audit_diff_file(args.diff_path)
+    else:
+        if sys.stdin.isatty():
+            parser.print_help()
+            sys.exit(1)
+        diff_text = sys.stdin.read()
+        res = audit_diff(diff_text)
+
+    if args.json:
+        print(json.dumps(res, indent=2))
+    else:
+        if res.get("status") == "PASSED":
+            print(f"[PASS] Diff Guard: Clean patch (+{res['additions_count']}/-{res['deletions_count']}). Zero security bypasses.")
+            sys.exit(0)
+        else:
+            print(f"[BLOCKED] Diff Guard: Found {res.get('total_violations', 0)} security invariant violation(s):")
+            for v in res.get("violations", []):
+                print(f"  - [{v['severity']}] {v['rule_id']} at {v['file']}:{v['line']} -> {v['description']}")
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/.torusguard/scripts/finding_scorer.py

@@ -0,0 +1,86 @@
+#!/usr/bin/env python3
+"""
+TorusGuard 5-Factor Finding Confidence Scorer
+Evaluates finding confidence against the objective 0–100 scoring model.
+"""
+
+import sys
+import json
+import argparse
+from typing import Dict, Any, Tuple
+
+def compute_confidence_score(
+    evidence_quality: int = 35,
+    reproduction_success: int = 0,
+    independent_confirmations: int = 5,
+    environmental_clarity: int = 15,
+    manual_review_status: int = 0
+) -> Tuple[int, str, Dict[str, int]]:
+    """
+    Computes total score and assigns confidence band.
+    Max points:
+    - evidence_quality: 35
+    - reproduction_success: 25
+    - independent_confirmations: 15
+    - environmental_clarity: 15
+    - manual_review_status: 10
+    """
+    eq = min(max(evidence_quality, 0), 35)
+    rs = min(max(reproduction_success, 0), 25)
+    ic = min(max(independent_confirmations, 0), 15)
+    ec = min(max(environmental_clarity, 0), 15)
+    mr = min(max(manual_review_status, 0), 10)
+
+    total = eq + rs + ic + ec + mr
+
+    if total >= 90:
+        band = "Confirmed"
+    elif total >= 70:
+        band = "High Confidence"
+    elif total >= 50:
+        band = "Medium Confidence"
+    else:
+        band = "Needs Review"
+
+    factors = {
+        "evidence_quality": eq,
+        "reproduction_success": rs,
+        "independent_confirmations": ic,
+        "environmental_clarity": ec,
+        "manual_review_status": mr,
+        "total_score": total,
+        "classification_band": band
+    }
+    return total, band, factors
+
+
+def main():
+    parser = argparse.ArgumentParser(description="TorusGuard Confidence Scorer")
+    parser.add_argument("--eq", type=int, default=35, help="Evidence quality score (0-35)")
+    parser.add_argument("--rs", type=int, default=0, help="Reproduction success score (0-25)")
+    parser.add_argument("--ic", type=int, default=5, help="Independent confirmations score (0-15)")
+    parser.add_argument("--ec", type=int, default=15, help="Environmental clarity score (0-15)")
+    parser.add_argument("--mr", type=int, default=0, help="Manual review status score (0-10)")
+    parser.add_argument("--json", action="store_true", help="Output JSON")
+    args = parser.parse_args()
+
+    total, band, factors = compute_confidence_score(
+        evidence_quality=args.eq,
+        reproduction_success=args.rs,
+        independent_confirmations=args.ic,
+        environmental_clarity=args.ec,
+        manual_review_status=args.mr
+    )
+
+    if args.json:
+        print(json.dumps(factors, indent=2))
+    else:
+        print(f"Total Confidence Score: {total}/100")
+        print(f"Classification Band: {band}")
+        print("Factor Breakdown:")
+        for k, v in factors.items():
+            if k not in ("total_score", "classification_band"):
+                print(f"  - {k}: {v}")
+
+if __name__ == "__main__":
+    main()