fableforge-agent 0.1.0__py3-none-any.whl

fableforge_agent/control_plane/core.py

@@ -0,0 +1,303 @@
+"""
+Control Plane core — sandboxed execution, audit trails, and incident response.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Sandbox
+# ═══════════════════════════════════════════════════════════════════════════════
+
+@dataclass
+class SandboxPolicy:
+    allow_network: bool = False
+    allowed_domains: List[str] = field(default_factory=list)
+    allowed_paths: List[str] = field(default_factory=list)
+    max_files: int = 100
+    max_memory_mb: int = 512
+    max_cpu_seconds: int = 60
+
+
+@dataclass
+class SandboxResult:
+    stdout: str = ""
+    stderr: str = ""
+    exit_code: int = 0
+    duration_ms: int = 0
+    violation: Optional[str] = None
+
+
+class Sandbox:
+    """Isolated execution environment for agent code and tool calls.
+
+    Supported backends: docker, subprocess (Linux seccomp), mock.
+    Falls back gracefully when a backend is unavailable.
+    """
+
+    def __init__(self, sandbox_type: str = "docker"):
+        self.sandbox_type = sandbox_type
+        self.policy = SandboxPolicy()
+
+    def _resolve_backend(self) -> str:
+        backend = self.sandbox_type
+        if backend == "docker":
+            try:
+                subprocess.run(
+                    ["docker", "version"],
+                    capture_output=True, timeout=5,
+                )
+                return "docker"
+            except Exception:
+                pass
+        if backend == "subprocess" or (backend == "docker" and sys.platform == "linux"):
+            return "subprocess"
+        return "mock"
+
+    def execute(self, code: str, timeout: int = 30) -> SandboxResult:
+        backend = self._resolve_backend()
+        start = time.monotonic()
+
+        if backend == "docker":
+            return self._exec_docker(code, timeout)
+        elif backend == "subprocess":
+            return self._exec_subprocess(code, timeout)
+        return self._exec_mock(code, timeout)
+
+    def _exec_docker(self, code: str, timeout: int) -> SandboxResult:
+        try:
+            with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+                f.write(code)
+                script_path = f.name
+            container = f"fableforge-sandbox-{uuid.uuid4().hex[:8]}"
+            mount = f"{script_path}:/tmp/script.py:ro"
+            proc = subprocess.run(
+                [
+                    "docker", "run", "--rm", "--name", container,
+                    "-v", mount,
+                    "--network", "none" if not self.policy.allow_network else "bridge",
+                    "--memory", f"{self.policy.max_memory_mb}m",
+                    "--cpus", "1",
+                    "python:3.11-slim", "python", "/tmp/script.py",
+                ],
+                capture_output=True, text=True, timeout=timeout,
+            )
+            os.unlink(script_path)
+            dur = int((time.monotonic() - start) * 1000)
+            return SandboxResult(
+                stdout=proc.stdout, stderr=proc.stderr,
+                exit_code=proc.returncode, duration_ms=dur,
+            )
+        except subprocess.TimeoutExpired:
+            dur = int((time.monotonic() - start) * 1000)
+            return SandboxResult(stderr="TIMEOUT", exit_code=-1, duration_ms=dur,
+                                violation="resource_exhaustion")
+        except Exception as e:
+            dur = int((time.monotonic() - start) * 1000)
+            return SandboxResult(stderr=str(e), exit_code=-1, duration_ms=dur)
+
+    def _exec_subprocess(self, code: str, timeout: int) -> SandboxResult:
+        start = time.monotonic()
+        try:
+            proc = subprocess.run(
+                [sys.executable, "-c", code],
+                capture_output=True, text=True, timeout=timeout,
+            )
+            dur = int((time.monotonic() - start) * 1000)
+            return SandboxResult(
+                stdout=proc.stdout, stderr=proc.stderr,
+                exit_code=proc.returncode, duration_ms=dur,
+            )
+        except subprocess.TimeoutExpired:
+            dur = int((time.monotonic() - start) * 1000)
+            return SandboxResult(stderr="TIMEOUT", exit_code=-1, duration_ms=dur,
+                                violation="resource_exhaustion")
+        except Exception as e:
+            dur = int((time.monotonic() - start) * 1000)
+            return SandboxResult(stderr=str(e), exit_code=-1, duration_ms=dur)
+
+    def _exec_mock(self, code: str, timeout: int) -> SandboxResult:
+        start = time.monotonic()
+        dur = int((time.monotonic() - start) * 1000)
+        return SandboxResult(
+            stdout=f"[mock] would execute {len(code)} chars",
+            exit_code=0, duration_ms=dur,
+        )
+
+    def file_read(self, path: str) -> str:
+        resolved = os.path.abspath(path)
+        if not self._path_allowed(resolved):
+            raise PermissionError(f"Read denied: {path}")
+        with open(resolved) as f:
+            return f.read()
+
+    def file_write(self, path: str, content: str) -> None:
+        resolved = os.path.abspath(path)
+        if not self._path_allowed(resolved):
+            raise PermissionError(f"Write denied: {path}")
+        with open(resolved, "w") as f:
+            f.write(content)
+
+    def network_access(self, host: str, port: int) -> bool:
+        if not self.policy.allow_network:
+            return False
+        if self.policy.allowed_domains:
+            return any(host.endswith(d) for d in self.policy.allowed_domains)
+        return True
+
+    def _path_allowed(self, resolved: str) -> bool:
+        if not self.policy.allowed_paths:
+            return True
+        return any(resolved.startswith(os.path.abspath(p)) for p in self.policy.allowed_paths)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# AuditTrail
+# ═══════════════════════════════════════════════════════════════════════════════
+
+@dataclass
+class AuditEntry:
+    id: str
+    timestamp: str
+    agent_id: str
+    action_type: str
+    details: Dict
+    severity: str
+    signature: Optional[str] = None
+    verified: bool = False
+
+
+class AuditTrail:
+    """Records every agent action for non-repudiation and forensics."""
+
+    def __init__(self, agent_id: str = "default"):
+        self.agent_id = agent_id
+        self._entries: Dict[str, AuditEntry] = {}
+
+    def record(self, action_type: str, details: Dict, severity: str = "info") -> AuditEntry:
+        entry = AuditEntry(
+            id=uuid.uuid4().hex,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            agent_id=self.agent_id,
+            action_type=action_type,
+            details=details,
+            severity=severity,
+        )
+        self._entries[entry.id] = entry
+        return entry
+
+    def export(self, fmt: str = "json") -> str:
+        if fmt == "markdown":
+            lines = ["# Audit Trail\n"]
+            for e in sorted(self._entries.values(), key=lambda x: x.timestamp):
+                lines.append(f"## {e.action_type} ({e.severity})\n")
+                lines.append(f"- **ID:** {e.id}\n")
+                lines.append(f"- **Time:** {e.timestamp}\n")
+                lines.append(f"- **Agent:** {e.agent_id}\n")
+                lines.append(f"- **Details:** `{json.dumps(e.details)}`\n")
+                if e.signature:
+                    lines.append(f"- **Signature:** `{e.signature[:32]}...`\n")
+                lines.append("\n")
+            return "".join(lines)
+        return json.dumps(
+            [e.__dict__ for e in sorted(self._entries.values(), key=lambda x: x.timestamp)],
+            indent=2,
+        )
+
+    def search(self, query: str) -> List[AuditEntry]:
+        q = query.lower()
+        return [
+            e for e in self._entries.values()
+            if q in e.action_type.lower()
+            or q in e.severity.lower()
+            or q in json.dumps(e.details).lower()
+        ]
+
+    def sign(self, entry_id: str) -> str:
+        entry = self._entries.get(entry_id)
+        if entry is None:
+            raise KeyError(f"No entry: {entry_id}")
+        try:
+            from cryptography.hazmat.primitives import hashes
+            from cryptography.hazmat.primitives.asymmetric import rsa, padding
+            private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+            data = json.dumps(entry.__dict__, sort_keys=True).encode()
+            sig = private_key.sign(data, padding.PKCS1v15(), hashes.SHA256())
+            entry.signature = sig.hex()
+            entry.verified = True
+        except ImportError:
+            entry.signature = f"unsigned-{uuid.uuid4().hex}"
+            entry.verified = False
+        return entry.signature
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# IncidentResponse
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_INCIDENT_PATTERNS = {
+    "data_exfiltration": ["curl", "wget", "nc ", "netcat", "ssh ", "scp "],
+    "prompt_injection": ["ignore previous", "ignore all", "system prompt:"],
+    "privilege_escalation": ["sudo", "chmod 777", "chown", "setuid"],
+    "resource_exhaustion": ["fork bomb", ":(){:|:&}", "while true"],
+}
+
+
+class IncidentResponse:
+    """Detects and responds to security incidents in agent behavior."""
+
+    def detect(self, entry: AuditEntry) -> Optional[str]:
+        if entry.action_type == "tool_call":
+            args_str = json.dumps(entry.details).lower()
+            for incident_type, patterns in _INCIDENT_PATTERNS.items():
+                for pat in patterns:
+                    if pat in args_str:
+                        return incident_type
+        if entry.severity == "critical":
+            if entry.details.get("bytes_sent", 0) > 1_000_000:
+                return "data_exfiltration"
+        return None
+
+    def respond(self, incident_type: str, entry: AuditEntry) -> str:
+        actions = {
+            "data_exfiltration": f"Blocked outbound transfer from {entry.agent_id}. "
+                                 "Network access revoked for this session.",
+            "prompt_injection": f"Prompt injection detected in entry {entry.id[:8]}. "
+                               "Message quarantined.",
+            "privilege_escalation": f"Privilege escalation attempt by {entry.agent_id}. "
+                                   "Sandbox policy tightened.",
+            "resource_exhaustion": f"Resource exhaustion from {entry.agent_id}. "
+                                    "Process terminated.",
+        }
+        return actions.get(incident_type, f"Unknown incident: {incident_type}")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ControlPlane (aggregate)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class ControlPlane:
+    """Top-level agent control plane combining sandbox, audit, and incident response.
+
+    This is the primary entry point for Tier 3 functionality.
+    """
+
+    def __init__(self, agent_id: str = "default", sandbox_type: str = "docker"):
+        self.agent_id = agent_id
+        self.sandbox = Sandbox(sandbox_type=sandbox_type)
+        self.audit = AuditTrail(agent_id=agent_id)
+        self.incidents = IncidentResponse()

fableforge_agent/observability/__init__.py

@@ -0,0 +1,29 @@
+"""
+Behavioral Observability — Tier 4 of FableForge Agent.
+
+Real-time agent behavior observation, semantic firewall, safety rules, and
+behavior reporting.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+from fableforge_agent.observability.core import (
+    BehavioralObservability,
+    Observation,
+    SemanticFirewall,
+    FirewallDecision,
+    SafetyRule,
+    BehaviorReport,
+)
+
+__all__ = [
+    "BehavioralObservability",
+    "Observation",
+    "SemanticFirewall",
+    "FirewallDecision",
+    "SafetyRule",
+    "BehaviorReport",
+]

fableforge_agent/observability/core.py

@@ -0,0 +1,229 @@
+"""
+Behavioral Observability core — real-time agent observation, semantic firewall,
+safety rules, and behavior reporting.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+import hashlib
+import json
+import re
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Generator
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Safety Rule & Firewall Decision
+# ═══════════════════════════════════════════════════════════════════════════════
+
+@dataclass
+@dataclass
+class SafetyRule:
+    name: str
+    pattern: str
+    action: str  # "block", "warn", "log"
+    description: str
+
+
+@dataclass
+class FirewallDecision:
+    allowed: bool
+    reason: str
+    severity: str  # "pass", "warn", "block"
+    matched_rule: Optional[str] = None
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Observation & BehaviorReport
+# ═══════════════════════════════════════════════════════════════════════════════
+
+@dataclass
+class Observation:
+    timestamp: str
+    agent_id: str
+    action_type: str
+    input_hash: str
+    output_hash: str
+    latency_ms: float
+    tool_calls: List[Dict] = field(default_factory=list)
+
+
+class BehaviorReport:
+    """Aggregated behavior analysis with safety, helpfulness, honesty, and
+    efficiency scores."""
+
+    def __init__(self, observations: Optional[List[Observation]] = None):
+        self.observations: List[Observation] = observations or []
+        self.violations: List[Dict] = []
+        self.scores: Dict[str, float] = {
+            "safety": 1.0,
+            "helpfulness": 1.0,
+            "honesty": 1.0,
+            "efficiency": 1.0,
+        }
+
+    def summary(self) -> str:
+        lines = ["╔═══════════════════════════════════════╗"]
+        lines.append("║        Behavior Report Summary       ║")
+        lines.append("╠═══════════════════════════════════════╣")
+        for metric, score in self.scores.items():
+            bar = "█" * int(score * 20)
+            pct = int(score * 100)
+            lines.append(f"║ {metric.capitalize():<12} {bar:20} {pct:3}% ║")
+        lines.append("╠═══════════════════════════════════════╣")
+        lines.append(f"║ Observations: {len(self.observations):>5}                 ║")
+        lines.append(f"║ Violations:   {len(self.violations):>5}                 ║")
+        lines.append("╚═══════════════════════════════════════╝")
+        if self.violations:
+            lines.append("\nViolations:")
+            for v in self.violations:
+                lines.append(f"  - {v.get('type', 'unknown')}: {v.get('description', '')}")
+        return "\n".join(lines)
+
+    def to_json(self) -> Dict:
+        return {
+            "observations": [o.__dict__ for o in self.observations],
+            "violations": self.violations,
+            "scores": self.scores,
+        }
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# SemanticFirewall
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_DEFAULT_RULES = [
+    SafetyRule(
+        name="system-prompt-override",
+        pattern=r"(?i)(ignore (previous|all|above)|system prompt:|you are now)",
+        action="block",
+        description="Attempts to override system prompt"),
+    SafetyRule(
+        name="dangerous-code",
+        pattern=r"(?i)(rm\s+-rf|shutdown|format|dd\s+if)",
+        action="block",
+        description="Dangerous system commands"),
+    SafetyRule(
+        name="credential-exposure",
+        pattern=r"(?i)(sk-[a-zA-Z0-9]{20,}|-----BEGIN\s+(RSA|EC|PRIVATE)\s+KEY-----)",
+        action="block",
+        description="Exposure of API keys or private keys"),
+    SafetyRule(
+        name="data-exfiltration",
+        pattern=r"(?i)(curl\s+https?://[^\s]*\s*\|)|(wget\s+-O\s*-)",
+        action="block",
+        description="Data exfiltration via pipe to network"),
+]
+
+
+class SemanticFirewall:
+    """Validates prompts, responses, and tool calls against safety rules."""
+
+    def __init__(self, rules: Optional[List[SafetyRule]] = None):
+        self.rules: List[SafetyRule] = rules or _DEFAULT_RULES
+
+    def check_input(self, prompt: str) -> FirewallDecision:
+        return self._check(prompt, "input")
+
+    def check_output(self, response: str) -> FirewallDecision:
+        return self._check(response, "output")
+
+    def check_tool_call(self, tool: str, args: Dict) -> FirewallDecision:
+        combined = json.dumps({"tool": tool, "args": args})
+        return self._check(combined, "tool_call")
+
+    def _check(self, content: str, context: str) -> FirewallDecision:
+        for rule in self.rules:
+            try:
+                if re.search(rule.pattern, content):
+                    severity = "block" if rule.action == "block" else rule.action
+                    return FirewallDecision(
+                        allowed=rule.action != "block",
+                        reason=f"Rule '{rule.name}' matched in {context}: {rule.description}",
+                        severity=severity,
+                        matched_rule=rule.name,
+                    )
+            except re.error:
+                continue
+        return FirewallDecision(allowed=True, reason="", severity="pass")
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# BehavioralObservability
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class BehavioralObservability:
+    """Real-time behavioral observability for agents.
+
+    Observes agent actions, runs analyzers, and exposes a stream of observations
+    compatible with websocket dashboards.
+    """
+
+    def __init__(self, agent_id: str = "default"):
+        self.agent_id = agent_id
+        self._observations: List[Observation] = []
+        self._firewall = SemanticFirewall()
+        self._subscribers: List[callable] = []
+
+    def observe(self, action: str, context: Dict) -> Observation:
+        input_str = json.dumps(context.get("input", ""))
+        output_str = json.dumps(context.get("output", ""))
+        obs = Observation(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            agent_id=self.agent_id,
+            action_type=action,
+            input_hash=hashlib.sha256(input_str.encode()).hexdigest()[:16],
+            output_hash=hashlib.sha256(output_str.encode()).hexdigest()[:16],
+            latency_ms=context.get("latency_ms", 0.0),
+            tool_calls=context.get("tool_calls", []),
+        )
+        self._observations.append(obs)
+        for sub in self._subscribers:
+            try:
+                sub(obs)
+            except Exception:
+                pass
+        return obs
+
+    def analyze(self, observations: Optional[List[Observation]] = None) -> BehaviorReport:
+        obs_list = observations or self._observations
+        report = BehaviorReport(observations=obs_list)
+        total = len(obs_list)
+        if total == 0:
+            return report
+        violations = 0
+        for o in obs_list:
+            dec = self._firewall.check_input(o.input_hash)
+            if not dec.allowed:
+                violations += 1
+                report.violations.append({
+                    "type": "firewall_block",
+                    "description": dec.reason,
+                    "timestamp": o.timestamp,
+                })
+        safe = 1.0 - (violations / max(total, 1))
+        report.scores["safety"] = max(0.0, safe)
+        avg_latency = sum(o.latency_ms for o in obs_list) / total
+        report.scores["efficiency"] = max(0.0, min(1.0, 1.0 / (1.0 + avg_latency / 1000)))
+        report.scores["helpfulness"] = max(0.0, 1.0 - 0.1 * violations)
+        return report
+
+    def stream(self) -> Generator[Observation, None, None]:
+        yield from self._observations
+
+    def subscribe(self, callback: callable) -> None:
+        self._subscribers.append(callback)
+
+    def check_semantic_intent(self, prompt: str, action: str) -> float:
+        prompt_words = set(prompt.lower().split())
+        action_words = set(action.lower().split())
+        if not prompt_words or not action_words:
+            return 0.0
+        overlap = prompt_words & action_words
+        return len(overlap) / max(len(prompt_words), len(action_words))

fableforge_agent/trust/__init__.py

@@ -0,0 +1,27 @@
+"""
+Trust Protocols — Tier 4 of FableForge Agent.
+
+Bidirectional agent-to-agent trust, identity registry, and permission
+framework.
+
+Author: KingLabsA
+  - GitHub: https://github.com/KingLabsA
+  - Twitter: https://x.com/KingLabsA
+  - Email: kinglabsa@users.noreply.github.com
+"""
+
+from fableforge_agent.trust.core import (
+    TrustProtocol,
+    HandshakeResult,
+    IdentityRegistry,
+    AgentIdentity,
+    PermissionFramework,
+)
+
+__all__ = [
+    "TrustProtocol",
+    "HandshakeResult",
+    "IdentityRegistry",
+    "AgentIdentity",
+    "PermissionFramework",
+]