xoras-agent-framework 2.0.0__tar.gz

xoras_agent_framework-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 XORAS Systems LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xoras_agent_framework-2.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: xoras-agent-framework
+Version: 2.0.0
+Summary: Enterprise Multi-Agent Runtime & AST Security Governance Framework
+Author-email: XORAS Systems LLC <engineering@xoras.ai>
+License: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: cryptography>=41.0.0
+Dynamic: license-file
+
+# XORAS Agentic Environment & Governance Framework v2.0
+
+[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://xoras.ai)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Security](https://img.shields.io/badge/AST%20Security-PASSED-success.svg)](#ast-static-security-gating)
+[![Build](https://img.shields.io/badge/tests-9%20passed-brightgreen.svg)](#testing)
+
+**XORAS Agentic Environment & Governance Framework** is an enterprise-grade multi-agent runtime, dynamic AST security scanner, and cryptographic provenance platform developed by **XORAS Systems LLC**.
+
+---
+
+## Key Features
+
+- **AST Static Security Gating (`env-integrity-sentry`)**: Real-time Abstract Syntax Tree parsing and secret scanning that intercepts dangerous code injections (`eval`, `exec`, `subprocess shell=True`) and credential leaks prior to execution.
+- **Cryptographic Trace Receipts (`xoras.evidence.v1`)**: Every agent state transition and tool invocation generates an Ed25519 / HMAC SHA-256 signed JSON-L trace receipt for 100% zero-falsification audit trails.
+- **Swarm Agent Orchestrator**: Multi-agent state graph pipeline coordinating **Architect**, **Engineer**, and **Auditor** roles with consensus gating and fallback remediation.
+- **Zero-Drift Specification (`.xorasrules` & `xoras.env.yaml`)**: Standardized environment rules, role permissions, memory hierarchies, and workspace boundary controls.
+- **Interactive Web Dashboard & Product Landing Page**: Embedded web UI serving live trace logs, AST playgrounds, and product metrics (`xoras serve`).
+
+---
+
+## Architecture Overview
+
+```mermaid
+flowchart TD
+    UserRequest["User / Trigger Payload"] --> SwarmOrchestrator["Swarm Orchestrator (Architect)"]
+    SwarmOrchestrator --> ASTEngine["AST Security Engine (Auditor)"]
+    
+    ASTEngine -- "Pass (Safety Score = 1.0)" --> RuntimeHarness["XORAS Runtime Harness (Engineer)"]
+    ASTEngine -- "Fail (Restricted Token)" --> RejectReceipt["Log Rejection & Signed Receipt"]
+    
+    RuntimeHarness --> ToolExec["Subprocess / File I/O Sandbox"]
+    ToolExec --> EvidenceSigner["Cryptographic Signer (HMAC / Ed25519)"]
+    EvidenceSigner --> JSONLTrace["xoras_agent_traces.jsonl"]
+```
+
+---
+
+## Quickstart & Installation
+
+### 1. Install Package
+```bash
+pip install xoras-agent-framework
+```
+
+### 2. Initialize Governance Environment
+```bash
+xoras init
+```
+This generates `.xorasrules` and `xoras.env.yaml` in your workspace root.
+
+### 3. Scan Scripts for AST Violations
+```bash
+xoras scan my_script.py
+```
+
+### 4. Run Scripts in Isolated Sandbox
+```bash
+xoras run my_script.py
+```
+
+### 5. Serve Interactive Web Dashboard
+```bash
+xoras serve --port 8080
+```
+Open `http://localhost:8080` to view the live product landing page and interactive AST playground.
+
+---
+
+## Python API Usage
+
+```python
+from xoras import XORASAgentEnvironment, SwarmOrchestrator
+
+# Initialize environment
+env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+
+# Run multi-agent orchestrator pipeline
+orchestrator = SwarmOrchestrator(env=env)
+result = orchestrator.run_pipeline(
+    task_description="Deploy verified configuration file",
+    code_payload='{"status": "active", "version": "2.0.0"}',
+    target_path="artifacts/deploy_config.json"
+)
+
+print("Pipeline Success:", result["success"])
+print("Trace Signature:", result["last_signature"])
+```
+
+---
+
+## Testing
+
+Run the automated test suite:
+```bash
+PYTHONPATH=. pytest tests/
+```
+
+---
+
+## Documentation
+
+- [AST Security Gating Specification](docs/architecture/AST_SECURITY_GATING.md)
+- [Cryptographic Provenance Receipts](docs/architecture/CRYPTOGRAPHIC_PROVENANCE.md)
+- [API Reference](docs/API_REFERENCE.md)
+
+---
+
+## License
+
+Distributed under the MIT Enterprise License. See `LICENSE` for details.  
+&copy; 2026 XORAS Systems LLC. All rights reserved.

xoras_agent_framework-2.0.0/README.md

@@ -0,0 +1,112 @@
+# XORAS Agentic Environment & Governance Framework v2.0
+
+[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://xoras.ai)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Security](https://img.shields.io/badge/AST%20Security-PASSED-success.svg)](#ast-static-security-gating)
+[![Build](https://img.shields.io/badge/tests-9%20passed-brightgreen.svg)](#testing)
+
+**XORAS Agentic Environment & Governance Framework** is an enterprise-grade multi-agent runtime, dynamic AST security scanner, and cryptographic provenance platform developed by **XORAS Systems LLC**.
+
+---
+
+## Key Features
+
+- **AST Static Security Gating (`env-integrity-sentry`)**: Real-time Abstract Syntax Tree parsing and secret scanning that intercepts dangerous code injections (`eval`, `exec`, `subprocess shell=True`) and credential leaks prior to execution.
+- **Cryptographic Trace Receipts (`xoras.evidence.v1`)**: Every agent state transition and tool invocation generates an Ed25519 / HMAC SHA-256 signed JSON-L trace receipt for 100% zero-falsification audit trails.
+- **Swarm Agent Orchestrator**: Multi-agent state graph pipeline coordinating **Architect**, **Engineer**, and **Auditor** roles with consensus gating and fallback remediation.
+- **Zero-Drift Specification (`.xorasrules` & `xoras.env.yaml`)**: Standardized environment rules, role permissions, memory hierarchies, and workspace boundary controls.
+- **Interactive Web Dashboard & Product Landing Page**: Embedded web UI serving live trace logs, AST playgrounds, and product metrics (`xoras serve`).
+
+---
+
+## Architecture Overview
+
+```mermaid
+flowchart TD
+    UserRequest["User / Trigger Payload"] --> SwarmOrchestrator["Swarm Orchestrator (Architect)"]
+    SwarmOrchestrator --> ASTEngine["AST Security Engine (Auditor)"]
+    
+    ASTEngine -- "Pass (Safety Score = 1.0)" --> RuntimeHarness["XORAS Runtime Harness (Engineer)"]
+    ASTEngine -- "Fail (Restricted Token)" --> RejectReceipt["Log Rejection & Signed Receipt"]
+    
+    RuntimeHarness --> ToolExec["Subprocess / File I/O Sandbox"]
+    ToolExec --> EvidenceSigner["Cryptographic Signer (HMAC / Ed25519)"]
+    EvidenceSigner --> JSONLTrace["xoras_agent_traces.jsonl"]
+```
+
+---
+
+## Quickstart & Installation
+
+### 1. Install Package
+```bash
+pip install xoras-agent-framework
+```
+
+### 2. Initialize Governance Environment
+```bash
+xoras init
+```
+This generates `.xorasrules` and `xoras.env.yaml` in your workspace root.
+
+### 3. Scan Scripts for AST Violations
+```bash
+xoras scan my_script.py
+```
+
+### 4. Run Scripts in Isolated Sandbox
+```bash
+xoras run my_script.py
+```
+
+### 5. Serve Interactive Web Dashboard
+```bash
+xoras serve --port 8080
+```
+Open `http://localhost:8080` to view the live product landing page and interactive AST playground.
+
+---
+
+## Python API Usage
+
+```python
+from xoras import XORASAgentEnvironment, SwarmOrchestrator
+
+# Initialize environment
+env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+
+# Run multi-agent orchestrator pipeline
+orchestrator = SwarmOrchestrator(env=env)
+result = orchestrator.run_pipeline(
+    task_description="Deploy verified configuration file",
+    code_payload='{"status": "active", "version": "2.0.0"}',
+    target_path="artifacts/deploy_config.json"
+)
+
+print("Pipeline Success:", result["success"])
+print("Trace Signature:", result["last_signature"])
+```
+
+---
+
+## Testing
+
+Run the automated test suite:
+```bash
+PYTHONPATH=. pytest tests/
+```
+
+---
+
+## Documentation
+
+- [AST Security Gating Specification](docs/architecture/AST_SECURITY_GATING.md)
+- [Cryptographic Provenance Receipts](docs/architecture/CRYPTOGRAPHIC_PROVENANCE.md)
+- [API Reference](docs/API_REFERENCE.md)
+
+---
+
+## License
+
+Distributed under the MIT Enterprise License. See `LICENSE` for details.  
+© 2026 XORAS Systems LLC. All rights reserved.

xoras_agent_framework-2.0.0/examples/01_basic_agent.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""
+XORAS Agentic Framework — Basic Agent Example
+Demonstrates environment initialization, tool execution, and signed trace receipts.
+"""
+
+from xoras import XORASAgentEnvironment
+
+def main():
+    print("=== XORAS Agent Framework — Basic Agent Example ===")
+    env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+
+    # Execute a safe file write tool
+    result = env.execute_tool(
+        agent_name="Engineer",
+        tool_name="file_write",
+        args={
+            "path": "artifacts/basic_agent_output.json",
+            "content": '{"message": "Hello from XORAS Agent Framework v2.0", "status": "active"}'
+        }
+    )
+
+    print("\nExecution Result:")
+    print("Success:", result.get("success"))
+    print("Path:", result.get("path"))
+    print("Receipt Signature:", result.get("receipt_signature"))
+
+if __name__ == "__main__":
+    main()

xoras_agent_framework-2.0.0/examples/02_secure_code_evaluator.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+"""
+XORAS Agentic Framework — AST Code Security Evaluator
+Demonstrates AST static analysis and rejection of unsafe dynamic code snippets.
+"""
+
+from xoras import ASTSecurityEngine
+
+def evaluate_snippets():
+    engine = ASTSecurityEngine()
+    
+    snippets = [
+        ("Safe Data Handler", "def process(x):\n    return x.strip().lower()\n"),
+        ("Dynamic Eval Snippet", "eval('import os; os.system(\"ls\")')\n"),
+        ("Unsafe Subprocess", "import subprocess\nsubprocess.Popen('rm -rf /tmp', shell=True)\n"),
+        ("Hardcoded API Key", "AWS_SECRET_ACCESS_KEY = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY'\n")
+    ]
+
+    print("=== XORAS AST Security Evaluator Demo ===")
+    for title, code in snippets:
+        res = engine.scan_code(code)
+        print(f"\n[Snippet]: {title}")
+        print(f"Status: {'SAFE [PASSED]' if res.is_safe else 'UNSAFE [REJECTED]'}")
+        print(f"Safety Score: {res.safety_score * 100:.1f}%")
+        if res.violations:
+            print("Violations:", res.violations)
+        if res.secrets_detected:
+            print("Secrets:", res.secrets_detected)
+
+if __name__ == "__main__":
+    evaluate_snippets()

xoras_agent_framework-2.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xoras-agent-framework"
+version = "2.0.0"
+description = "Enterprise Multi-Agent Runtime & AST Security Governance Framework"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "XORAS Systems LLC", email = "engineering@xoras.ai" }]
+requires-python = ">=3.9"
+dependencies = [
+    "pyyaml>=6.0",
+    "cryptography>=41.0.0",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[project.scripts]
+xoras = "xoras.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]

xoras_agent_framework-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xoras_agent_framework-2.0.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()

xoras_agent_framework-2.0.0/tests/test_ast_security.py

@@ -0,0 +1,47 @@
+"""
+Unit tests for XORAS AST Security Engine.
+"""
+
+import pytest
+from xoras.ast_security import ASTSecurityEngine
+
+def test_ast_safe_code():
+    engine = ASTSecurityEngine()
+    code = """
+def calculate_sum(a, b):
+    return a + b
+
+print(calculate_sum(10, 20))
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is True
+    assert result.safety_score == 1.0
+    assert len(result.violations) == 0
+
+def test_ast_forbidden_eval():
+    engine = ASTSecurityEngine()
+    code = """
+x = 10
+eval("print(x)")
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is False
+    assert any("eval()" in v for v in result.violations)
+
+def test_ast_forbidden_exec():
+    engine = ASTSecurityEngine()
+    code = """
+exec("import os; os.system('ls')")
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is False
+    assert any("exec()" in v for v in result.violations)
+
+def test_ast_secret_leak_detection():
+    engine = ASTSecurityEngine()
+    code = """
+AWS_SECRET_ACCESS_KEY = "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+"""
+    result = engine.scan_code(code)
+    assert result.is_safe is False
+    assert len(result.secrets_detected) > 0

xoras_agent_framework-2.0.0/tests/test_runtime.py

@@ -0,0 +1,42 @@
+"""
+Unit tests for XORAS Agentic Runtime & Orchestrator.
+"""
+
+import os
+from xoras.runtime import XORASAgentEnvironment
+from xoras.orchestrator import SwarmOrchestrator
+
+def test_runtime_file_write_and_read():
+    env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+    write_res = env.execute_tool("Engineer", "file_write", {
+        "path": "artifacts/test_artifact.json",
+        "content": '{"version": "2.0.0", "status": "active"}'
+    })
+    assert write_res["success"] is True
+    assert "receipt_signature" in write_res
+
+    read_res = env.execute_tool("Engineer", "file_read", {
+        "path": "artifacts/test_artifact.json"
+    })
+    assert read_res["success"] is True
+    assert "active" in read_res["content"]
+
+def test_runtime_ast_rejection():
+    env = XORASAgentEnvironment(config_path="xoras.env.yaml")
+    unsafe_res = env.execute_tool("Engineer", "file_write", {
+        "path": "artifacts/bad.py",
+        "content": 'eval("print(\'unsafe\')")'
+    })
+    assert unsafe_res["success"] is False
+    assert "blocked by XORAS AST security" in unsafe_res["error"]
+
+def test_swarm_orchestrator_pipeline():
+    orch = SwarmOrchestrator()
+    res = orch.run_pipeline(
+        task_description="Deploy secure configuration manifest",
+        code_payload='{"config": "valid_json"}',
+        target_path="artifacts/swarm_output.json"
+    )
+    assert res["success"] is True
+    assert res["stage"] == "COMPLETED"
+    assert res["safety_score"] == 1.0

xoras_agent_framework-2.0.0/tests/test_signer.py

@@ -0,0 +1,27 @@
+"""
+Unit tests for XORAS Cryptographic Signer.
+"""
+
+from xoras.signer import CryptographicSigner
+
+def test_evidence_receipt_signing_and_verification():
+    signer = CryptographicSigner()
+    payload = {"path": "test.txt", "content": "hello world"}
+    receipt = signer.sign_receipt("Engineer", "file_write", payload, "SUCCESS")
+    
+    assert receipt.version == "xoras.evidence.v1"
+    assert receipt.organization == "XORAS Systems LLC"
+    assert receipt.status == "SUCCESS"
+    assert receipt.signature is not None
+    
+    # Verify signature mathematically
+    assert signer.verify_receipt(receipt) is True
+
+def test_evidence_receipt_tamper_rejection():
+    signer = CryptographicSigner()
+    payload = {"path": "test.txt", "content": "hello world"}
+    receipt = signer.sign_receipt("Engineer", "file_write", payload, "SUCCESS")
+    
+    # Tamper with status
+    receipt.status = "FAILED"
+    assert signer.verify_receipt(receipt) is False

xoras_agent_framework-2.0.0/xoras/__init__.py

@@ -0,0 +1,23 @@
+"""
+XORAS Systems LLC — Agentic Environment & Governance Framework
+Enterprise-grade multi-agent runtime, AST static security gating, and cryptographic provenance receipts.
+"""
+
+__version__ = "2.0.0"
+__author__ = "XORAS Systems LLC"
+
+from .config import XORASConfig
+from .ast_security import ASTSecurityEngine, ASTScanResult
+from .signer import CryptographicSigner, EvidenceReceipt
+from .runtime import XORASAgentEnvironment
+from .orchestrator import SwarmOrchestrator
+
+__all__ = [
+    "XORASConfig",
+    "ASTSecurityEngine",
+    "ASTScanResult",
+    "CryptographicSigner",
+    "EvidenceReceipt",
+    "XORASAgentEnvironment",
+    "SwarmOrchestrator",
+]

xoras_agent_framework-2.0.0/xoras/ast_security.py

@@ -0,0 +1,141 @@
+"""
+XORAS Systems LLC — AST Security Engine & Secret Scanner
+Performs strict Abstract Syntax Tree (AST) static analysis and entropy secret detection.
+"""
+
+import ast
+import re
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+@dataclass
+class ASTScanResult:
+    is_safe: bool
+    violations: List[str] = field(default_factory=list)
+    secrets_detected: List[str] = field(default_factory=list)
+    safety_score: float = 1.0
+    nodes_analyzed: int = 0
+
+class ASTSecurityVisitor(ast.NodeVisitor):
+    def __init__(self):
+        self.violations: List[str] = []
+        self.nodes_analyzed: int = 0
+        
+        # Unsafe call names
+        self.forbidden_calls = {
+            "eval": "Dynamic evaluation via eval() is strictly prohibited by XORAS AST Guardrails.",
+            "exec": "Dynamic execution via exec() is strictly prohibited by XORAS AST Guardrails.",
+            "compile": "Dynamic compilation via compile() is prohibited in agent runtime.",
+            "__import__": "Dynamic import via __import__ is prohibited.",
+        }
+        
+        # Unsafe module imports
+        self.dangerous_modules = {
+            "ctypes": "Raw memory manipulation via ctypes is restricted.",
+            "pty": "Pseudo-terminal creation via pty is prohibited.",
+            "code": "Interactive interpreter via code module is restricted."
+        }
+
+    def visit(self, node):
+        self.nodes_analyzed += 1
+        super().visit(node)
+
+    def visit_Call(self, node):
+        # Inspect function call names
+        func_name = None
+        if isinstance(node.func, ast.Name):
+            func_name = node.func.id
+        elif isinstance(node.func, ast.Attribute):
+            func_name = node.func.attr
+            
+        if func_name in self.forbidden_calls:
+            self.violations.append(f"Line {getattr(node, 'lineno', '?')}: {self.forbidden_calls[func_name]}")
+            
+        # Check os.system / subprocess.Popen with unsafe args
+        if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name):
+            module_name = node.func.value.id
+            if module_name == "os" and func_name in ("system", "popen", "execv", "execl"):
+                # Inspect string argument if available
+                if node.args and isinstance(node.args[0], ast.Constant):
+                    arg_val = str(node.args[0].value)
+                    if "rm -rf" in arg_val or "sudo " in arg_val or "> /dev/" in arg_val:
+                        self.violations.append(f"Line {getattr(node, 'lineno', '?')}: High-risk shell command in os.{func_name}: '{arg_val}'")
+            elif module_name == "subprocess" and func_name in ("Popen", "call", "run"):
+                # Check shell=True kwargs
+                for keyword in node.keywords:
+                    if keyword.arg == "shell" and isinstance(keyword.value, ast.Constant) and keyword.value.value is True:
+                        self.violations.append(f"Line {getattr(node, 'lineno', '?')}: Subprocess invocation with shell=True is restricted under XORAS AST policy.")
+
+        self.generic_visit(node)
+
+    def visit_Import(self, node):
+        for alias in node.names:
+            if alias.name in self.dangerous_modules:
+                self.violations.append(f"Line {getattr(node, 'lineno', '?')}: {self.dangerous_modules[alias.name]}")
+        self.generic_visit(node)
+
+    def visit_ImportFrom(self, node):
+        if node.module in self.dangerous_modules:
+            self.violations.append(f"Line {getattr(node, 'lineno', '?')}: {self.dangerous_modules[node.module]}")
+        self.generic_visit(node)
+
+
+class ASTSecurityEngine:
+    SECRET_PATTERNS = [
+        (r'(?i)(?:aws_access_key_id|aws_secret_access_key|api_key|secret_key|private_key)\s*[:=]\s*["\']([^"\']{8,})["\']', "Hardcoded API / Secret Key"),
+        (r'AKIA[0-9A-Z]{16}', "AWS Access Key ID"),
+        (r'sk_live_[0-9a-zA-Z]{24,}', "Stripe Live API Key"),
+        (r'sk-(?:proj-)?[a-zA-Z0-9_-]{32,}', "OpenAI API Key"),
+        (r'sk-ant-[a-zA-Z0-9_-]{32,}', "Anthropic API Key"),
+        (r'AIzaSy[0-9a-zA-Z_-]{33}', "Google Gemini API Key"),
+        (r'xox[baprs]-[0-9a-zA-Z]{10,48}', "Slack OAuth / Bot Token"),
+        (r'ghp_[0-9a-zA-Z]{36}', "GitHub Personal Access Token"),
+        (r'-----BEGIN\s+(?:RSA|EC|OPENSSH|PRIVATE)\s+KEY-----', "Private Cryptographic Key Block"),
+    ]
+
+    def __init__(self, strict_mode: bool = True):
+        self.strict_mode = strict_mode
+
+    def scan_code(self, code_snippet: str) -> ASTScanResult:
+        """Parses python AST syntax tree and runs regex secret scanning."""
+        violations: List[str] = []
+        secrets_detected: List[str] = []
+        
+        # 1. Secret scanning across raw code
+        for pattern, desc in self.SECRET_PATTERNS:
+            matches = re.findall(pattern, code_snippet)
+            if matches:
+                secrets_detected.append(f"Secret Leak Warning: Detected {desc} pattern in code payload.")
+                violations.append(f"Secret Scanner: High-entropy token matching '{desc}' found.")
+
+        # 2. Syntax validation & AST parsing
+        nodes_analyzed = 0
+        try:
+            tree = ast.parse(code_snippet)
+            visitor = ASTSecurityVisitor()
+            visitor.visit(tree)
+            violations.extend(visitor.violations)
+            nodes_analyzed = visitor.nodes_analyzed
+        except SyntaxError as e:
+            # If not python syntax (e.g. bash script), fallback to regex heuristic scanner
+            nodes_analyzed = len(code_snippet.splitlines())
+            forbidden_heuristics = [
+                (r'\beval\s*\(', "Dynamic eval() invocation"),
+                (r'\bexec\s*\(', "Dynamic exec() invocation"),
+                (r'rm\s+-rf\s+/', "Destructive root filesystem command 'rm -rf /'"),
+                (r':\(\)\{\s*:\|:&\s*\};:', "Fork bomb pattern"),
+            ]
+            for pat, msg in forbidden_heuristics:
+                if re.search(pat, code_snippet):
+                    violations.append(f"Heuristic AST Fallback Violation: Detected forbidden pattern '{msg}'")
+
+        is_safe = len(violations) == 0
+        safety_score = max(0.0, 1.0 - (len(violations) * 0.35))
+        
+        return ASTScanResult(
+            is_safe=is_safe,
+            violations=violations,
+            secrets_detected=secrets_detected,
+            safety_score=round(safety_score, 4),
+            nodes_analyzed=nodes_analyzed
+        )