torusguard 2.1.0 → 2.1.2

package/.torusguard/.manifest.json

@@ -10,6 +10,46 @@
   "config/scope.json": "b198a86186b4c6d5e1af516bf4e3a6afa8878e622ca1d57a5bf72d294f8c6f25",
   "config/slash-commands.json": "305c1dc5b556e8d64ad9dd585dafac1a9955cf1bd5321429955b19b7a62736b6",
   "config/torusguard.json": "55dbde335997421a01c97709fd1672ad70fa921bfe8346dd57552b799db2419e",
+  "core/__init__.py": "2120562452ae03c84468d67246dc93376f7ebcde8e4ca767c6253bc92c35dbbf",
+  "core/agent_roles.py": "d7189dbf1d3ae4e330eb316bed5d399a18992295addf466f4c6552bc14ae6a34",
+  "core/ast_walker.py": "309564d168e6eb9e3e93aceb29a95a61872b35a4da7235ee49e79e9d3a5e7cc6",
+  "core/authorization.py": "2bb7f85b4639959276fc7cfd427df7edb8b1f97f8003707a0032f100953d1b30",
+  "core/browser_verifier.py": "e450bdbb8d5c2808a3b3ea7bc33bce2451230cbbb7ed4f17dbc7107ab0f30d56",
+  "core/bundle.py": "82505fba44a5ad867a4caef34e1233ebf76d4bc2e15b943e2413822602f1a95f",
+  "core/call_graph.py": "7e230f8b5fa7dd8f780eafbe7381f2d9538f01a880c1349c41139cce20f9094f",
+  "core/clustering.py": "0ffcad5e8a459084d200248de8799d466c2b53ad627b778314b09f2733df782c",
+  "core/confidence.py": "81c6242a1a3eaea873d39e8b212e5781a2df2316614f18a2fe6ef757561f5bb5",
+  "core/cross_file_taint.py": "1fa323529e5ca2fcce06167e4a59431f9f8217ad7a5097f8afbc6b9a9dc0913d",
+  "core/exploit_checker.py": "74a48e6e1e1b9791107b487ab5434540494946441605cf9115fa90b787bc5c5a",
+  "core/formatter.py": "a9d2a20e52caaf8a801f65f325b3f5bc430eb6301506973095961d4615b7e429",
+  "core/governance.py": "657edfa332c2f855f917545862c9d38f31468cec464d11dd2c012dcf794fb32c",
+  "core/identity.py": "f42d3d81c7ee8ca5d2ef08d48066abdc42d2ccbd5fe0bbd88b35d5c8174b696f",
+  "core/import_resolver.py": "4ac89ac405816b7de599fbabfa47556d10c1557d92f3a700bf50b90f52ba6c75",
+  "core/incremental.py": "8ff9d41f6667bf567d2e952f31ae330271ba1d6cf5411ab4468c355ca2fa6681",
+  "core/lifecycle.py": "f4406acba8464ed9111128ef545f8c576639cadda8b9de7e23ff8a90fad24f9e",
+  "core/models.py": "ed23b50aab2eb7ea9bc16dbb20b0bf4f978f3aae7f39f0a713f7efe08ff238b5",
+  "core/parallel.py": "27fcfdd3760d481ffdd4e7321a79d17ef4823dd3744687fcc9d00349c0bb1d49",
+  "core/parser.py": "2f01e9beb178e86002fd8dd3211cf269ab59f21e5c65aabb5e9d0e110504d1d1",
+  "core/rechecker.py": "2a21b788158cac79db9030db79e3a27021e7f66692c37c39e0bd3fadf483388c",
+  "core/replay_trace.py": "8132cb43dd4593cc96f09f014c2b3882ef5296ebc5029a921423263b07ca7a1d",
+  "core/rules_registry.py": "80c4f5067f151b596388ae9a4546d2f009f10342daa5221412e5c9a222b27a31",
+  "core/run_folder.py": "cc8702dfd3a2768e5dca74f7ac85e316f53f1acb059bad87ca3650eeeae2defa",
+  "core/run_manager.py": "2470ebc8b54edaab3679d909fde48f02c7530f1e12c917b7b5cd5c004062a8b6",
+  "core/runtime_evidence.py": "79c947a3b131c3be2f2938789d12647a0d9010bb4077bf3f33b2c7218ba9028b",
+  "core/runtime_validator.py": "39477ef1138e8deaa5c3859d6402e71d2c0eb6e2e39fbd3db04fe3ad8e2c798c",
+  "core/safety_gate.py": "349e84187930faf79baa38643712d48636de504e8613667e42ec852999efa9fb",
+  "core/sarif.py": "93316e7d5fa0ac3660ce18307a2ef4f9c2b2b24b0a4e40d288f94edd0ef84e6d",
+  "core/stack_profiler.py": "8c5166c712d7e9341d6290b2220da05662f1ba251899d6f501a9875625f5539c",
+  "core/symbol_table.py": "8e700e01e920e7c8a496a16e400195bb6cedd9e3624997fbb44b29124e256d74",
+  "core/taint.py": "f54b3e2d620d480969681847e63149b259876dbac470dc417e90407e1def925b",
+  "core/taint_graph.py": "2f697a4d4c44801f346f7bde0794cc70c481b4a5a28fe02add20fa845fd9a5c5",
+  "core/taint_rules.py": "d29893e0212a2afb21fede6c20afb6d3fe9ff89511659675f02a034ea1e87d8f",
+  "core/v070_reporter.py": "d9e9bebd4e158f4c1b1b50897c04c2c5f9db85919b1700b47331ecf16fe7bd63",
+  "core/v070_workflow.py": "57bf1468c78f47b4aa5fb5804eb3c247825daa0933bb5cf0aad4ae2394adcead",
+  "core/v6_reporter.py": "95fa2ec5b0e708101b62131152445039192382e409d0f40c35cdcbf96648ca26",
+  "core/v6_workflow.py": "3e38afafc3afdbebe8cf76ed24da00435aab27a2ac512a292983f8b1e88ebcb8",
+  "core/watcher.py": "b3d4856023ee2f6c65b2938d3c76c246d7c440c58cdc7b642dc27209d68a959a",
+  "custom_rules/README.md": "282d35795e77a9def907155b068ba2949fd459f80de1d0d037b21777c5c9a718",
   "references/csharp-security.md": "d6e267855b08ed4fdff26f3b876f089ae1f90a7ec6546cba7e8173380d9daa9d",
   "references/django-security.md": "26ea5535ac435e61489df1e381ac62b19e81702edfe095e78c937be93fa15ea7",
   "references/drf-security.md": "c6796398317b0f264d89fff598404e126d819e69e1ea0a5129924a5eb2a7af9d",
@@ -43,6 +83,8 @@
   "rules/TG-INPUT-004-unrestricted-file-upload.md": "d665fb7ede456c24d12229cec22b30374a4dc036c3fe3a41ece22f97ab78a1f4",
   "rules/TG-INPUT-005-unsafe-template-rendering-and-escaping.md": "b6006e741a303d8ff2cd65ef417e6199e5dcf8fe7d603941244db82f6cbe1753",
   "rules/TG-INPUT-006-unsafe-file-path-traversal.md": "5edb665cd2c41b659849c96d0d4b801a6365e130be12c51733a3d6f17cfd85ed",
+  "rules/TG-INPUT-007-unvalidated-redirect.md": "7da41ecbd39a7c90fe90fc683df48f38b0cf5a0d7c2b027f0827830bd8f814f7",
+  "rules/TG-INPUT-008-insecure-deserialization.md": "5f5f85a9429d32959f890f668ff1fd75bd7ce976a7b9406c3b7235fc728989ca",
   "rules/TG-PLATFORM-001-wildcard-cors-with-credentials.md": "fb8154f5b8051e94886c956b1e7bdbc5f316739795b8fb9bb493223ca774fe25",
   "rules/TG-PLATFORM-002-missing-security-headers.md": "207f489453d6256b5d794f79be25c66e9f932ae5cb561b3e8b50d26a28f6a07a",
   "rules/TG-PLATFORM-003-production-stack-trace-exposure.md": "298c75b928c160720243e42ce5bf43397e73cf50ed472482d5ef3f7635fcb839",
@@ -155,14 +197,16 @@
   "schemas/retest.schema.json": "97c0407ca4365a524020c430912f686f698cc0de90043194621071e9fc681cc7",
   "schemas/runtime-evidence.schema.json": "929d2b094c1cd1f7f9db07be1eba5994e8002477eab3fd24140e1e973fd18cc1",
   "scripts/apply_runner.py": "b145a68a4bc10fcacb853f972aee81fa3607e32d282b2b850c5a63d8e72da890",
-  "scripts/audit_runner.py": "bc1e06ea5153ae326c4ad1de5d0cbb9503e618186623bea7cb8bb64d7b7b05ec",
+  "scripts/audit_runner.py": "18ebcd46f8363169db4ff4675a5258e0b93df5b219650de95b9a5e9f51da5ff9",
+  "scripts/deliberation_tournament.py": "52b130eb2031dd411a6f52e82e9b83caf800c4ecbdef29d6b0c848f02b528e3d",
   "scripts/diff_guard.py": "0dc178cdde1ac0ae1a1ea4b2eb2ce1756b2126f6156909cf55d85249f115fcbd",
-  "scripts/finding_scorer.py": "a5315be6ee256c01c4539da3d1905ebc8d0840a356b83c55f9f6f2654a9f0c60",
+  "scripts/finding_scorer.py": "95c7edfe5ee4742be565914f71bb07bd077b2cf4636b769476345389dd85f3cf",
   "scripts/harden_runner.py": "5d5a40029c088ccb66790a9b0128bdefcd35883ef1dac78088ceb9531392a8f1",
   "scripts/html_reporter.py": "655c57be39e13c177db8842ef471664e5853f3e43b9f2a63e590df40ff9c16cb",
   "scripts/manifest_builder.py": "f1f9a0d63c55cf5ff45e9fd39d1b251c2bce05e777f8c1e325741d340f0128db",
   "scripts/memory_engine.py": "b715d0ca030e95eb06ad6eda99027535df8a7e37d64897c023be6a291cf13dc6",
   "scripts/monorepo_detector.py": "5603674136a5294ebfff89efeca0a546dd4a7deb1d184a2592ff21aff2131f73",
+  "scripts/reachability_analyzer.py": "2cf509b5b5e7081f1852fe9a72d7d1d61b29ea5bba55b751b64fed439eb2548f",
   "scripts/recheck_runner.py": "89e93fcc6843493d7e5f0bf97065dbdb40106273a00e07f903250665ca25f6fb",
   "scripts/recipes_runner.py": "090c06ef0de3c640a111c5646837233ceeaca494b161bd5edc630cc1371dca0e",
   "scripts/report_sync.py": "5ebef684690200694a53af30db850d9808d03ec710ed21ef75c4de52b5e5217c",
@@ -170,10 +214,12 @@
   "scripts/run_manager.py": "b738ff70879e46547d32fac6befc61de9599f676411384280fb9819ea3ad7035",
   "scripts/safety_gate.py": "3379b7534b2590cf563717a448983ad8ed7e8f174f0ad65683d33e8a10f51558",
   "scripts/sarif_exporter.py": "86700765212adb3ab590ca72614bf3ad4ce7ce60e3193f7f3bd1a04d34d10f6e",
+  "scripts/skill_profiler.py": "ada83e022795febb2365a73753656ff881993d77cf73517e818d668e961adb45",
   "scripts/stack_detect.py": "c05a1ade4c8692025476bf7ea080a8f07c92e5d8e9a04f94c1654386352ffbdc",
   "scripts/status_runner.py": "4c358c91950c7874bcc6a5f23f2d3fda62b0752efcf6c6b658adf02ed77c7752",
+  "scripts/stride_generator.py": "c7a4ea2a19a7386dfc6c0fb301e933a32de2c8963ffa605e5aaa651cf880507f",
   "scripts/term_ui.py": "ca69398f85c86fe89526d6334b3ee866c890273997351113c3cc1765b7bd20c3",
-  "skills/torusguard/SKILL.md": "4987faed0081cd75d54b9f3c8378a2539e348e8ec814ffdb78415ed7d478a571",
+  "skills/torusguard/SKILL.md": "15c69cb10eca1a10344b494888dce57e2baf227c3282bd54424a36ce35fb2460",
   "skills/torusguard/bootstrap.py": "f7ce48cc310dcdbf86c028f05a8f5ad22677f4cebb1bec5c90d173a9044342c5",
   "skills/torusguard/references/auth-and-sessions.md": "c3e4b9600cb53fc28c993922dc880accbec5783ac90d5ee98d63b52762d19525",
   "skills/torusguard/references/business-logic-and-abuse.md": "58e87df2864d468af70c1ff39f5d540c687fa846b671457f85046ab2065fe99c",
@@ -205,7 +251,7 @@
   "skills/torusguard/references/websocket-security.md": "b5315e49432184c006664436d689d426b7322fc6fbbba2899a9ea5e5bab74c92",
   "skills/torusguard-ai-guard/SKILL.md": "130a24d82f1b92fcc3ac2f4edc77d4d999ae629971f2131f66d6fac876f5593f",
   "skills/torusguard-apply/SKILL.md": "edb21eabae4f9ad5be5976b20d217941c87b2a15edfc73383d02460ca3253fca",
-  "skills/torusguard-audit/SKILL.md": "527f7fca458efb814ef656626d080adacc8c1dd95f2d56a457bbae688a9bedaa",
+  "skills/torusguard-audit/SKILL.md": "b9ffc74381360656cbc78438c003fb1e67c4f0787f87627555863b474d57a8ad",
   "skills/torusguard-authorize/SKILL.md": "56bcebc718bddadfd66010ebe2d23b4acf429e6230de05dd2300dab6bd383cc2",
   "skills/torusguard-container/SKILL.md": "f9a2dea0b6b1e2de8ce4a189bb32b1010f1b4d6ff7a529450857b6dab20546ff",
   "skills/torusguard-exploit-check/SKILL.md": "c127f1766e98e28dc967e452dff5dfec87689a26cf671ab6e62a135cd4d46e4b",
@@ -217,7 +263,9 @@
   "skills/torusguard-recheck/SKILL.md": "a5c4539ec6d091179c8ba53792fba46f26795976f392d2305e357f25a2966c55",
   "skills/torusguard-redos/SKILL.md": "b09b39bd98589613b2107c177e247f6224fb54ab2f028b4339ae01aac9d28c67",
   "skills/torusguard-report/SKILL.md": "509185ea6730601cf9a44e136219cace61cd0523f8e112de03e4ef1c35e60585",
+  "skills/torusguard-review/SKILL.md": "6d9ec907821ddf62bbbeaed8751d1532e72ba42702ea3afdaadaf720f66c35e3",
   "skills/torusguard-status/SKILL.md": "e9741a20313a8304bc7565b194949a59ec7cfd4945b197517680164b3197efc0",
+  "skills/torusguard-threatmodel/SKILL.md": "549903f39a030a75d88c184b7373d86bca921d8f802732c3674bfe9537b14537",
   "skills/torusguard-verify/SKILL.md": "aeb4d3c7924253607d130e48491d83bf7b7a21707cd1dac2ba97d64f5e259fd6",
   "skills/torusguard-web-validate/SKILL.md": "f1df00e10abd823d9a8c4daa1a3af7f26c5263c6c8e58e05b61b647d01a25489",
   "templates/audit-report.template.md": "71149dd05b01a74287a47781fdc71fd2d1b4b70337da303bf78767d0410a6c90",
@@ -226,7 +274,7 @@
   "templates/remediation-bundle.template.md": "4d85a540e3a2e74f9b21fc8a2a1072e27ca03e97cd67ca482f529cfe722acc4d",
   "workflows/ai-guard.md": "7d762f4e18f64864b50b64148b972085d2766aeaf13833bc1e6aeb8fddb96999",
   "workflows/apply.md": "0cd0fa84627ff73ffef84aa7eed6d096b57826139c079fa63f1bd745e13b138a",
-  "workflows/audit.md": "4fb2bfe345792572f3e164aa38ab1b103868eac2bff0d9dbf91082514ea9b649",
+  "workflows/audit.md": "9f13b0497553965d30a71ff040a0dc556d526c8bbff136952b8210685632b5d7",
   "workflows/authorize.md": "386779f405c4b7de0282938db4095179ed212fd32296dff158acb3258b41aec1",
   "workflows/container.md": "64936b4873e9dfde6deae8a7d10d572a3bfbbfe9ef2340d0df8a3db5e1d02ad7",
   "workflows/exploit-check.md": "4dc4016b7a22f18d5c32dd6fcfa7a859df07d03300973654aea92fe5251c8a85",
@@ -238,7 +286,9 @@
   "workflows/recheck.md": "f57194675ed465ee5fd6e8fc731e7102becd2dd0a8f8848517c0e11d3de849cf",
   "workflows/redos.md": "f55a4f510849a5ea7e2ae4b08ecc70dff03c1bf21c7fdc664a4ff3ad0396f904",
   "workflows/report.md": "7c718dfef6da1b66ba0fed300b7dfc90438fc3866af5a9b2aae4b3c3acd638e2",
+  "workflows/review.md": "ac8edc3c1d64571c7d58769e471fb10855969de72d874acb988c9c3c963f9a45",
   "workflows/status.md": "021a962ae4e6fc81383db2ef42d28dcfc1b3e546c9a10a7a15b9910e531cf0c2",
+  "workflows/threatmodel.md": "b509c38754bff5284d768d3e64cea21839ee9abcedb1661e597d291145715cf1",
   "workflows/verify.md": "dd2579fe7d6e31ba47a4094edfbf4ab04be0745da7dc79e104b0547395c715d1",
   "workflows/web-validate.md": "08441b01d15fd16f6697a95244632ea1465193631ecfb0746fe0c58895ff1c2b"
 }

package/.torusguard/core/__init__.py

@@ -0,0 +1,146 @@
+"""
+TorusGuard Core Architecture & Security Workflow Engine (v0.7.0)
+
+Tiered architectural layers:
+- Tier 1: Canonical Data Models, Lifecycle State Machine & Reporting (v0.5 base)
+- Tier 2: Governed Remediation, Clustering, Patch Policy & SARIF Export (v0.6 engine)
+- Tier 3: Authorized Runtime Validation, Exploitability Confirmation & Multi-Agent Roles (v0.7 engine)
+"""
+
+# ==============================================================================
+# Tier 1: Canonical Data Models, Lifecycle & Provenance (v0.5 base)
+# ==============================================================================
+from .models import (
+    Finding,
+    Evidence,
+    Remediation,
+    FrameworkPattern,
+    AffectedComponent,
+    ReproductionMethod,
+    RetestRecord,
+    NotesRecord,
+    FindingTimestamps,
+    ProvenanceChain,
+    ConfidenceScore,
+    ConfidenceFactors,
+    ConfidenceBand,
+    SeverityLevel,
+    SeverityInfo,
+    RemediationPriority,
+    FindingStatus,
+    LifecycleStage,
+    TaxonomyCategory,
+    EvidenceType,
+    AuditReport,
+    mask_sensitive_data,
+)
+from .lifecycle import FindingLifecycleManager, LifecycleTransitionError
+from .formatter import ReportFormatter
+from .run_folder import RunFolder
+
+# ==============================================================================
+# Tier 2: Governed Remediation, Clustering, Patch Policy & SARIF (v0.6 engine)
+# ==============================================================================
+from .identity import IdentityEngine, FindingFingerprint
+from .clustering import ClusteringEngine, RootCauseCluster
+from .bundle import BundleManager, RemediationBundle
+from .governance import PatchGovernor, PatchPolicyDecision, HIGH_RISK_KEYWORDS, SENSITIVE_CATEGORIES
+from .rechecker import TargetedRechecker, TargetedRecheckResult, RecheckOutcome
+from .run_manager import RunManager
+from .sarif import SarifExporter
+from .v6_reporter import V6Reporter
+from .v6_workflow import V6Workflow
+from .stack_profiler import StackProfiler, StackProfile
+
+# ==============================================================================
+# Tier 3: Authorized Runtime Validation & Exploitability Confirmation (v0.7 engine)
+# ==============================================================================
+from .authorization import AuthorizationManager, AuthorizationRecord, TargetScope, AuthorizationError
+from .safety_gate import SafetyGate, SafetyDecision, SafetyReviewLevel
+from .runtime_evidence import EvidenceCollector, RuntimeEvidenceItem, RedactionEngine
+from .runtime_validator import WebValidator, SessionState
+from .exploit_checker import ExploitChecker, ExploitCheckResult, ExploitabilityStatus
+from .browser_verifier import BrowserVerifier, BrowserAction
+from .agent_roles import RoleOrchestrator, RoleHandoff, AgentRole
+from .replay_trace import ReplayManager, ReplayTrace, ReplayStep
+from .v070_reporter import V070Reporter
+from .v070_workflow import V070Workflow
+
+__version__ = "0.7.0"
+
+__all__ = [
+    # Tier 1: Canonical Models & Lifecycle
+    "Finding",
+    "Evidence",
+    "Remediation",
+    "FrameworkPattern",
+    "AffectedComponent",
+    "ReproductionMethod",
+    "RetestRecord",
+    "NotesRecord",
+    "FindingTimestamps",
+    "ProvenanceChain",
+    "ConfidenceScore",
+    "ConfidenceFactors",
+    "ConfidenceBand",
+    "SeverityLevel",
+    "SeverityInfo",
+    "RemediationPriority",
+    "FindingStatus",
+    "LifecycleStage",
+    "TaxonomyCategory",
+    "EvidenceType",
+    "AuditReport",
+    "mask_sensitive_data",
+    "FindingLifecycleManager",
+    "LifecycleTransitionError",
+    "ReportFormatter",
+    "RunFolder",
+    # Tier 2: Governed Remediation & v0.6 Engine
+    "IdentityEngine",
+    "FindingFingerprint",
+    "ClusteringEngine",
+    "RootCauseCluster",
+    "BundleManager",
+    "RemediationBundle",
+    "PatchGovernor",
+    "PatchPolicyDecision",
+    "HIGH_RISK_KEYWORDS",
+    "SENSITIVE_CATEGORIES",
+    "TargetedRechecker",
+    "TargetedRecheckResult",
+    "RecheckOutcome",
+    "RunManager",
+    "SarifExporter",
+    "V6Reporter",
+    "V6Workflow",
+    "StackProfiler",
+    "StackProfile",
+    # Tier 3: Authorized Runtime Validation & v0.7 Engine
+    "AuthorizationManager",
+    "AuthorizationRecord",
+    "TargetScope",
+    "AuthorizationError",
+    "SafetyGate",
+    "SafetyDecision",
+    "SafetyReviewLevel",
+    "EvidenceCollector",
+    "RuntimeEvidenceItem",
+    "RedactionEngine",
+    "WebValidator",
+    "SessionState",
+    "ExploitChecker",
+    "ExploitCheckResult",
+    "ExploitabilityStatus",
+    "BrowserVerifier",
+    "BrowserAction",
+    "RoleOrchestrator",
+    "RoleHandoff",
+    "AgentRole",
+    "ReplayManager",
+    "ReplayTrace",
+    "ReplayStep",
+    "V070Reporter",
+    "V070Workflow",
+]
+

package/.torusguard/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/.torusguard/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