xybern 2.0.0__py3-none-any.whl

xybern/__init__.py

@@ -0,0 +1,29 @@
+"""
+Xybern — identity & authorisation infrastructure for AI agents.
+
+Install once; Xybern discovers every AI agent in your system, gives each a
+cryptographic identity, and (when you turn enforcement on) authorises every
+action before it executes.
+
+Quick start::
+
+    from xybern import auto
+    auto.connect()          # uses the key from `xybern login`, env, or config
+
+    # discovers frameworks + agents + tools, registers them to your workspace
+    # (each gets a DID), and instruments them in OBSERVE mode by default.
+
+CLI::
+
+    xybern login            # device-code browser flow (auto-picks your workspace key)
+    xybern agents           # dry-run: show what would be discovered
+    xybern status
+    xybern enforce on       # switch from observe to active authorisation
+"""
+
+from . import auto
+from .config import Config
+
+__version__ = "2.0.0"
+
+__all__ = ["auto", "Config", "__version__"]

xybern/auto.py

@@ -0,0 +1,167 @@
+"""The one-line entrypoint: discover, register (with identity), instrument.
+
+    from xybern import auto
+    auto.connect()
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from . import discovery
+from .client import XybernClient
+from .config import Config
+
+log = logging.getLogger("xybern")
+
+
+@dataclass
+class ConnectResult:
+    authenticated: bool
+    mode: str
+    frameworks: List[str] = field(default_factory=list)
+    agents: List[str] = field(default_factory=list)
+    instrumented: List[str] = field(default_factory=list)
+    workspace: Optional[str] = None
+
+    def summary(self) -> str:
+        lines = [
+            f"✓ Detected frameworks: {', '.join(self.frameworks) or 'none'}",
+            f"✓ Found {len(self.agents)} agent(s)/tool(s)",
+        ]
+        if self.authenticated:
+            lines.append(f"✓ Registered to workspace (each issued an identity)")
+            lines.append(f"✓ Mode: {self.mode.upper()}" +
+                         (" — actions logged, nothing blocked yet" if self.mode == "observe" else " — authorising actions"))
+        else:
+            lines.append("⚠ Not connected — run `xybern login` (or set XYBERN_API_KEY) to register + govern")
+        return "\n".join(lines)
+
+
+class _Registrar:
+    """Idempotently maps discovered agents → registered agent_ids (with identity)."""
+    def __init__(self, client: XybernClient, cfg: Config):
+        self.client = client
+        self.cfg = cfg
+        self._by_key: Dict[str, str] = {}     # name|framework -> agent_id
+        self._loaded = False
+
+    def _key(self, name: str, framework: str) -> str:
+        return f"{framework}|{name}".lower()
+
+    def _load_existing(self):
+        if self._loaded or not self.cfg.authenticated:
+            return
+        self._loaded = True
+        try:
+            data = self.client.list_agents()
+            for a in (data.get("agents") or []):
+                self._by_key[self._key(a.get("name", ""), a.get("framework", ""))] = a.get("agent_id")
+        except Exception:
+            pass
+
+    def ensure(self, info: "discovery.AgentInfo") -> Optional[str]:
+        if not self.cfg.authenticated:
+            return None
+        self._load_existing()
+        k = self._key(info.name, info.framework)
+        if k in self._by_key:
+            return self._by_key[k]
+        try:
+            resp = self.client.register_agent(
+                name=info.name, framework=info.framework,
+                capabilities=info.capabilities or [],
+                description=f"Auto-discovered {info.kind} via Xybern SDK",
+            )
+            agent_id = (resp.get("agent") or {}).get("agent_id")
+            if agent_id:
+                self._by_key[k] = agent_id
+            return agent_id
+        except Exception as e:
+            log.debug("xybern: register failed for %s: %s", info.name, e)
+            return None
+
+
+_STATE: Dict = {"connected": False}
+
+
+def connect(api_key: Optional[str] = None, mode: Optional[str] = None,
+            frameworks: Optional[List[str]] = None, instrument: bool = True,
+            **overrides) -> ConnectResult:
+    """Discover agents, register them (with cryptographic identity), and instrument
+    the detected frameworks. OBSERVE mode by default — nothing is ever blocked until
+    you switch to enforce (`xybern enforce on` or mode="enforce")."""
+    cfg = Config.resolve(api_key=api_key, mode=mode, frameworks=frameworks, **overrides)
+    client = XybernClient(cfg)
+
+    from .telemetry import Telemetry
+    tel = Telemetry(client, cfg)
+    tel.start()
+    registrar = _Registrar(client, cfg)
+
+    # 1) inventory whatever already exists, register each
+    found = discovery.discover_all(cfg.frameworks)
+    for a in found:
+        registrar.ensure(a)
+
+    # 2) the action hook used by all framework interceptors
+    def hook(framework, action_type, agent_name, content, metadata) -> bool:
+        return _on_action(cfg, client, tel, registrar, framework, action_type,
+                          agent_name, content, metadata)
+
+    def on_discover(info):
+        registrar.ensure(info)
+
+    instrumented = []
+    if instrument:
+        instrumented = discovery.instrument_all(hook, on_discover, cfg.frameworks)
+
+    _STATE.update({"connected": True, "cfg": cfg, "client": client,
+                   "telemetry": tel, "registrar": registrar})
+
+    return ConnectResult(
+        authenticated=cfg.authenticated, mode=cfg.mode,
+        frameworks=discovery.detected_frameworks(cfg.frameworks),
+        agents=[a.name for a in found], instrumented=instrumented,
+        workspace=cfg.workspace,
+    )
+
+
+def _on_action(cfg, client, tel, registrar, framework, action_type, agent_name,
+               content, metadata) -> bool:
+    """Return True to allow, False to block. OBSERVE always allows (logs only)."""
+    agent_id = None
+    if agent_name:
+        from .discovery import AgentInfo
+        agent_id = registrar.ensure(AgentInfo(name=agent_name, framework=framework))
+
+    if cfg.mode != "enforce":
+        # observe: enqueue, never block
+        if cfg.authenticated:
+            ev = {"action_type": action_type, "agent_id": agent_id,
+                  "metadata": {"framework": framework, **(metadata or {})}}
+            if content is not None:
+                ev["metadata"]["content_sha256"] = hashlib.sha256(
+                    content.encode("utf-8", "replace")).hexdigest()
+            tel.record(ev)
+        return True
+
+    # enforce: synchronous decision, fail-open per config
+    if not cfg.authenticated:
+        return True
+    try:
+        result = client.intercept(action_type=action_type, action_content=content,
+                                  agent_id=agent_id,
+                                  metadata={"framework": framework, **(metadata or {})})
+        decision = result.get("decision", "allow")
+        return decision == "allow"
+    except Exception:
+        return cfg.fail_open
+
+
+def status() -> Dict:
+    return {"connected": _STATE.get("connected", False),
+            "mode": getattr(_STATE.get("cfg"), "mode", None)}

xybern/cli/__main__.py

@@ -0,0 +1,158 @@
+"""`xybern` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import socket
+import sys
+import time
+
+from ..config import (Config, DEFAULT_BASE_URL, save_credentials, clear_credentials,
+                      set_mode)
+from ..client import XybernClient
+
+
+def _client(api_key=None) -> XybernClient:
+    base = os.environ.get("XYBERN_BASE_URL", DEFAULT_BASE_URL)
+    return XybernClient(Config(api_key=api_key, base_url=base))
+
+
+# ── commands ──────────────────────────────────────────────────────────────────
+
+def cmd_login(args) -> int:
+    base = os.environ.get("XYBERN_BASE_URL", DEFAULT_BASE_URL)
+
+    # Path 1 — explicit/paste key (or env). Validate then save.
+    api_key = args.api_key or os.environ.get("XYBERN_API_KEY")
+    if api_key:
+        cli = _client(api_key)
+        try:
+            cli.whoami()
+        except Exception as e:
+            print(f"✗ Could not validate that API key: {e}", file=sys.stderr)
+            return 1
+        save_credentials(api_key, base_url=base)
+        print("✓ Logged in with API key. Credentials saved to ~/.xybern/credentials.json")
+        return 0
+
+    # Path 2 — device-code browser flow (auto-picks your workspace key)
+    cli = _client()
+    try:
+        start = cli.device_auth_start(hostname=socket.gethostname())
+    except Exception as e:
+        print(f"✗ Device login unavailable ({e}).\n"
+              f"  Use:  xybern login --api-key xb_...   (create a key in your Xybern dashboard)",
+              file=sys.stderr)
+        return 1
+
+    url = start.get("verification_url") or start.get("verification_uri")
+    user_code = start.get("user_code")
+    device_code = start.get("device_code")
+    interval = int(start.get("interval", 5))
+    expires = int(start.get("expires_in", 600))
+
+    print("\nTo authorise this machine, open:\n")
+    print(f"    {url}")
+    print(f"\nand enter the code:  {user_code}\n")
+    try:
+        import webbrowser
+        webbrowser.open(url)
+    except Exception:
+        pass
+
+    print("Waiting for approval…", end="", flush=True)
+    deadline = time.time() + expires
+    while time.time() < deadline:
+        time.sleep(interval)
+        print(".", end="", flush=True)
+        try:
+            poll = cli.device_auth_poll(device_code)
+        except Exception:
+            continue
+        if poll.get("api_key"):
+            save_credentials(poll["api_key"], base_url=base, workspace=poll.get("workspace"))
+            print(f"\n✓ Logged in to workspace {poll.get('workspace') or ''}. "
+                  f"Credentials saved.")
+            return 0
+        if poll.get("status") in ("denied", "expired"):
+            print(f"\n✗ Login {poll['status']}.", file=sys.stderr)
+            return 1
+    print("\n✗ Timed out waiting for approval.", file=sys.stderr)
+    return 1
+
+
+def cmd_logout(args) -> int:
+    clear_credentials()
+    print("✓ Logged out.")
+    return 0
+
+
+def cmd_agents(args) -> int:
+    from .. import discovery
+    fw = discovery.detected_frameworks()
+    found = discovery.discover_all()
+    print(f"✓ Detected frameworks: {', '.join(fw) or 'none'}")
+    print(f"✓ Found {len(found)} agent(s)/tool(s) already instantiated"
+          + ("" if found else " (more appear as your app creates them)"))
+    by_fw = {}
+    for a in found:
+        by_fw.setdefault(a.framework, []).append(a)
+    for f, items in by_fw.items():
+        print(f"  • {f}: " + ", ".join(sorted({i.name for i in items}))[:200])
+    cfg = Config.resolve()
+    if not cfg.authenticated:
+        print("\n⚠ Not connected. Run `xybern login`, then `auto.connect()` in your app "
+              "to register these agents (each gets an identity).")
+    return 0
+
+
+def cmd_status(args) -> int:
+    cfg = Config.resolve()
+    print(f"Base URL:  {cfg.base_url}")
+    print(f"Mode:      {cfg.mode}")
+    print(f"Auth:      {'✓ logged in' if cfg.authenticated else '✗ not logged in'}")
+    if cfg.authenticated:
+        try:
+            n = len((_client(cfg.api_key).list_agents().get('agents') or []))
+            print(f"Workspace: {cfg.workspace or '(linked)'} · {n} registered agent(s)")
+        except Exception as e:
+            print(f"Workspace: (could not reach control plane: {e})")
+    return 0
+
+
+def cmd_enforce(args) -> int:
+    if args.state == "on":
+        set_mode("enforce")
+        print("✓ Enforcement ON — actions will be authorised (allow/block/escalate) on next connect.")
+    else:
+        set_mode("observe")
+        print("✓ Enforcement OFF — observe only (actions logged, nothing blocked).")
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="xybern", description="Xybern — identity & authorisation for AI agents")
+    sub = p.add_subparsers(dest="cmd")
+
+    lp = sub.add_parser("login", help="Authenticate this machine (device code, or --api-key)")
+    lp.add_argument("--api-key", help="Use an API key directly instead of the browser flow")
+    lp.set_defaults(func=cmd_login)
+
+    sub.add_parser("logout", help="Remove stored credentials").set_defaults(func=cmd_logout)
+    sub.add_parser("agents", help="Discover agents/tools in this project (dry run)").set_defaults(func=cmd_agents)
+    sub.add_parser("status", help="Show login + mode").set_defaults(func=cmd_status)
+
+    ep = sub.add_parser("enforce", help="Turn enforcement on/off")
+    ep.add_argument("state", choices=["on", "off"])
+    ep.set_defaults(func=cmd_enforce)
+
+    args = p.parse_args(argv)
+    if not getattr(args, "func", None):
+        p.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

xybern/client.py

@@ -0,0 +1,83 @@
+"""Thin REST client for the Xybern control plane."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .config import Config
+
+
+class XybernClient:
+    def __init__(self, config: Config):
+        self.cfg = config
+        self._session = requests.Session()
+        if config.api_key:
+            self._session.headers.update({"X-API-Key": config.api_key})
+        self._session.headers.update({"User-Agent": "xybern-sdk/2.0"})
+
+    # ── low level ────────────────────────────────────────────────────────────
+    def _url(self, path: str) -> str:
+        return f"{self.cfg.base_url.rstrip('/')}/{path.lstrip('/')}"
+
+    def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        r = self._session.post(self._url(path), json=body, timeout=self.cfg.timeout)
+        r.raise_for_status()
+        return r.json()
+
+    def _get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        r = self._session.get(self._url(path), params=params or {}, timeout=self.cfg.timeout)
+        r.raise_for_status()
+        return r.json()
+
+    # ── agents / registration ────────────────────────────────────────────────
+    def register_agent(self, name: str, framework: str = "custom",
+                        description: Optional[str] = None,
+                        capabilities: Optional[List[str]] = None,
+                        permissions: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Register (or idempotently re-register) an agent; returns agent + credential."""
+        return self._post("/enforce/agents", {
+            "name": name,
+            "framework": framework,
+            "description": description,
+            "capabilities": capabilities or [],
+            "permissions": permissions or {},
+        })
+
+    def list_agents(self) -> Dict[str, Any]:
+        return self._get("/enforce/agents")
+
+    # ── enforcement ────────────────────────────────────────────────────────────
+    def intercept(self, action_type: str, action_content: Optional[str] = None,
+                  agent_id: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None,
+                  ) -> Dict[str, Any]:
+        """Authorise one action. Respects redact (sends a content hash by default)."""
+        body: Dict[str, Any] = {"action_type": action_type, "agent_id": agent_id,
+                                "metadata": metadata or {}}
+        if action_content is not None:
+            if self.cfg.redact:
+                body["metadata"]["content_sha256"] = hashlib.sha256(
+                    action_content.encode("utf-8", "replace")).hexdigest()
+                body["action_content"] = None
+            else:
+                body["action_content"] = action_content
+        return self._post("/enforce/intercept", body)
+
+    def batch_intercept(self, actions: List[Dict[str, Any]]) -> Dict[str, Any]:
+        return self._post("/enforce/batch", {"actions": actions})
+
+    def list_policies(self) -> Dict[str, Any]:
+        return self._get("/enforce/policies")
+
+    def whoami(self) -> Dict[str, Any]:
+        """Lightweight auth/workspace check (lists agents; 200 => key valid)."""
+        return self._get("/enforce/agents")
+
+    # ── device-code login ──────────────────────────────────────────────────────
+    def device_auth_start(self, hostname: str) -> Dict[str, Any]:
+        return self._post("/auth/device/start", {"hostname": hostname, "client": "xybern-sdk"})
+
+    def device_auth_poll(self, device_code: str) -> Dict[str, Any]:
+        return self._post("/auth/device/poll", {"device_code": device_code})

xybern/config.py

@@ -0,0 +1,91 @@
+"""Configuration + credential resolution for the Xybern SDK.
+
+Resolution order for the API key (first hit wins):
+  1. explicit api_key=... passed to auto.connect()/Config
+  2. env XYBERN_API_KEY
+  3. ~/.xybern/credentials.json  (written by `xybern login`)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+DEFAULT_BASE_URL = "https://www.xybern.com/api/v1"
+CONFIG_DIR = Path(os.environ.get("XYBERN_HOME", str(Path.home() / ".xybern")))
+CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+
+
+def _read_credentials_file() -> Dict[str, Any]:
+    try:
+        return json.loads(CREDENTIALS_FILE.read_text())
+    except Exception:
+        return {}
+
+
+def save_credentials(api_key: str, base_url: str = DEFAULT_BASE_URL,
+                     workspace: Optional[str] = None) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_FILE.write_text(json.dumps({
+        "api_key": api_key, "base_url": base_url, "workspace": workspace,
+    }, indent=2))
+    try:
+        os.chmod(CREDENTIALS_FILE, 0o600)  # don't leave the key world-readable
+    except Exception:
+        pass
+
+
+def clear_credentials() -> None:
+    try:
+        CREDENTIALS_FILE.unlink()
+    except Exception:
+        pass
+
+
+def set_mode(mode: str) -> None:
+    """Persist the enforcement mode (observe|enforce) for future connects."""
+    creds = _read_credentials_file()
+    creds["mode"] = mode
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_FILE.write_text(json.dumps(creds, indent=2))
+
+
+@dataclass
+class Config:
+    """Resolved SDK configuration."""
+    api_key: Optional[str] = None
+    base_url: str = DEFAULT_BASE_URL
+    # "observe" = log/registry only, never blocks. "enforce" = act on decisions.
+    mode: str = "observe"
+    # If Xybern is unreachable, allow the action through (True) or block (False).
+    fail_open: bool = True
+    # Send hashes of action content instead of raw content.
+    redact: bool = True
+    # Frameworks to instrument; None = all detected. [] = none (discovery only).
+    frameworks: Optional[list] = None
+    timeout: float = 10.0
+    workspace: Optional[str] = None
+    extra: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def resolve(cls, api_key: Optional[str] = None, **overrides) -> "Config":
+        creds = _read_credentials_file()
+        key = api_key or os.environ.get("XYBERN_API_KEY") or creds.get("api_key")
+        base = (overrides.pop("base_url", None)
+                or os.environ.get("XYBERN_BASE_URL")
+                or creds.get("base_url") or DEFAULT_BASE_URL)
+        mode = (overrides.pop("mode", None) or os.environ.get("XYBERN_MODE")
+                or creds.get("mode") or "observe")
+        cfg = cls(api_key=key, base_url=base, mode=mode,
+                  workspace=creds.get("workspace"))
+        for k, v in overrides.items():
+            if hasattr(cfg, k) and v is not None:
+                setattr(cfg, k, v)
+        return cfg
+
+    @property
+    def authenticated(self) -> bool:
+        return bool(self.api_key and self.api_key.startswith("xb_"))

xybern/discovery/__init__.py

@@ -0,0 +1,109 @@
+"""Framework auto-discovery + instrumentation.
+
+We never "scan the machine". We inspect what's *already importable / imported* in
+the running process and (when instrumenting) hook the creation + execution points
+of supported frameworks. Everything is best-effort and defensive: a detector that
+can't find an expected internal simply reports presence and no-ops — it must never
+crash the host application.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+from typing import Callable, List, Optional
+
+
+@dataclass
+class AgentInfo:
+    name: str
+    framework: str
+    kind: str = "agent"                 # agent | tool | workflow | mcp_server
+    capabilities: List[str] = field(default_factory=list)
+
+    def fingerprint(self) -> str:
+        """Stable id for idempotent registration (survives restarts)."""
+        raw = f"{self.framework}|{self.kind}|{self.name}"
+        return "xagt_" + hashlib.sha256(raw.encode()).hexdigest()[:20]
+
+
+# Callback the host process calls before an action executes.
+# Signature: (framework, action_type, agent_name, content, metadata) -> bool(allow)
+ActionHook = Callable[[str, str, Optional[str], Optional[str], dict], bool]
+
+
+class Detector:
+    framework: str = "base"
+    module_hint: str = ""               # top-level module that signals presence
+
+    def available(self) -> bool:
+        try:
+            if self.module_hint in sys.modules:
+                return True
+            return importlib.util.find_spec(self.module_hint) is not None
+        except Exception:
+            return False
+
+    def imported(self) -> bool:
+        return self.module_hint in sys.modules
+
+    def scan(self) -> List[AgentInfo]:
+        """Best-effort inventory of already-instantiated agents/tools."""
+        return []
+
+    def instrument(self, hook: ActionHook, on_discover: Callable[[AgentInfo], None]) -> bool:
+        """Hook creation/execution points. Return True if any hook was installed."""
+        return False
+
+
+# ── registry ────────────────────────────────────────────────────────────────
+
+def _all_detectors() -> List[Detector]:
+    from . import detectors  # late import to avoid cycles
+    return detectors.build()
+
+
+def get_detectors(frameworks: Optional[List[str]] = None,
+                  available_only: bool = True) -> List[Detector]:
+    dets = _all_detectors()
+    if frameworks is not None:
+        wanted = {f.lower() for f in frameworks}
+        dets = [d for d in dets if d.framework.lower() in wanted]
+    if available_only:
+        dets = [d for d in dets if _safe(d.available, default=False)]
+    return dets
+
+
+def discover_all(frameworks: Optional[List[str]] = None) -> List[AgentInfo]:
+    found: List[AgentInfo] = []
+    for d in get_detectors(frameworks):
+        found.extend(_safe(d.scan, default=[]) or [])
+    # de-dupe by fingerprint
+    seen, out = set(), []
+    for a in found:
+        fp = a.fingerprint()
+        if fp not in seen:
+            seen.add(fp); out.append(a)
+    return out
+
+
+def detected_frameworks(frameworks: Optional[List[str]] = None) -> List[str]:
+    return [d.framework for d in get_detectors(frameworks)]
+
+
+def instrument_all(hook: ActionHook, on_discover: Callable[[AgentInfo], None],
+                   frameworks: Optional[List[str]] = None) -> List[str]:
+    instrumented = []
+    for d in get_detectors(frameworks):
+        if _safe(lambda: d.instrument(hook, on_discover), default=False):
+            instrumented.append(d.framework)
+    return instrumented
+
+
+def _safe(fn, default=None):
+    try:
+        return fn()
+    except Exception:
+        return default

xybern/discovery/detectors.py

@@ -0,0 +1,358 @@
+"""Per-framework detectors. Every hook is defensive — guarded by hasattr and
+wrapped so a version mismatch degrades to "presence detected" rather than crashing
+the host application."""
+
+from __future__ import annotations
+
+import gc
+from typing import Callable, List
+
+from . import AgentInfo, Detector, ActionHook
+
+
+# ── shared helpers ────────────────────────────────────────────────────────────
+
+def _wrap(cls, method_name: str, make_wrapper) -> bool:
+    """Replace cls.method_name with make_wrapper(orig); idempotent."""
+    orig = getattr(cls, method_name, None)
+    if orig is None or getattr(orig, "_xybern_wrapped", False):
+        return False
+    wrapper = make_wrapper(orig)
+    try:
+        wrapper._xybern_wrapped = True
+    except Exception:
+        pass
+    setattr(cls, method_name, wrapper)
+    return True
+
+
+def _enforce(hook: ActionHook, framework: str, action_type: str,
+             agent: str = None, content: str = None, meta: dict = None):
+    """Call the host hook; raise PolicyBlocked if it denies. Never lets unrelated errors propagate."""
+    try:
+        allow = hook(framework, action_type or "action", agent, content, meta or {})
+    except Exception:
+        return  # telemetry/transport hiccup must not break the agent (fail-open handled upstream)
+    if allow is False:
+        from ..exceptions import PolicyBlocked
+        raise PolicyBlocked(action_type or "action")
+
+
+def _scan(cls, framework: str, kind: str, name_attrs: List[str]) -> List[AgentInfo]:
+    out = []
+    try:
+        for o in gc.get_objects():
+            if isinstance(o, cls):
+                nm = None
+                for at in name_attrs:
+                    nm = getattr(o, at, None)
+                    if nm:
+                        break
+                out.append(AgentInfo(name=str(nm or type(o).__name__), framework=framework, kind=kind))
+    except Exception:
+        pass
+    return out
+
+
+# ── LangChain ────────────────────────────────────────────────────────────────
+
+class LangChainDetector(Detector):
+    framework = "langchain"
+    module_hint = "langchain_core"
+
+    def _tool_cls(self):
+        import langchain_core.tools as t
+        return t.BaseTool
+
+    def scan(self):
+        if not self.imported():
+            return []
+        try:
+            return _scan(self._tool_cls(), self.framework, "tool", ["name"])
+        except Exception:
+            return []
+
+    def instrument(self, hook, on_discover):
+        import langchain_core.tools as t
+        BaseTool = t.BaseTool
+        ok = False
+        for m in ("run", "arun", "_run", "invoke"):
+            def mk(orig):
+                def wrapper(self, *a, **k):
+                    name = getattr(self, "name", type(self).__name__)
+                    try:
+                        on_discover(AgentInfo(name=name, framework="langchain", kind="tool"))
+                    except Exception:
+                        pass
+                    _enforce(hook, "langchain", str(name), content=_firststr(a, k))
+                    return orig(self, *a, **k)
+                return wrapper
+            ok = _wrap(BaseTool, m, mk) or ok
+        return ok
+
+
+# ── CrewAI ──────────────────────────────────────────────────────────────────
+
+class CrewAIDetector(Detector):
+    framework = "crewai"
+    module_hint = "crewai"
+
+    def scan(self):
+        if not self.imported():
+            return []
+        try:
+            import crewai
+            return _scan(crewai.Agent, self.framework, "agent", ["role", "name"])
+        except Exception:
+            return []
+
+    def instrument(self, hook, on_discover):
+        import crewai
+        ok = False
+
+        def mk_init(orig):
+            def wrapper(self, *a, **k):
+                orig(self, *a, **k)
+                try:
+                    on_discover(AgentInfo(name=str(getattr(self, "role", None) or "crew-agent"),
+                                          framework="crewai", kind="agent",
+                                          capabilities=[getattr(t, "name", "") for t in (getattr(self, "tools", []) or [])]))
+                except Exception:
+                    pass
+            return wrapper
+        ok = _wrap(crewai.Agent, "__init__", mk_init) or ok
+
+        for meth in ("execute_task",):
+            def mk(orig):
+                def wrapper(self, *a, **k):
+                    _enforce(hook, "crewai", "execute_task",
+                             agent=str(getattr(self, "role", None) or "crew-agent"))
+                    return orig(self, *a, **k)
+                return wrapper
+            ok = _wrap(crewai.Agent, meth, mk) or ok
+        return ok
+
+
+# ── OpenAI Agents SDK (`agents` package) ──────────────────────────────────────
+
+class OpenAIAgentsDetector(Detector):
+    framework = "openai-agents"
+    module_hint = "agents"
+
+    def scan(self):
+        if not self.imported():
+            return []
+        try:
+            import agents
+            return _scan(agents.Agent, self.framework, "agent", ["name"])
+        except Exception:
+            return []
+
+    def instrument(self, hook, on_discover):
+        import agents
+        ok = False
+
+        def mk_init(orig):
+            def wrapper(self, *a, **k):
+                orig(self, *a, **k)
+                try:
+                    on_discover(AgentInfo(name=str(getattr(self, "name", "agent")),
+                                          framework="openai-agents", kind="agent"))
+                except Exception:
+                    pass
+            return wrapper
+        ok = _wrap(getattr(agents, "Agent", object), "__init__", mk_init) or ok
+
+        # Function tools expose on_invoke_tool / a callable; wrap if present.
+        FunctionTool = getattr(agents, "FunctionTool", None)
+        if FunctionTool is not None:
+            for meth in ("on_invoke_tool", "invoke", "run"):
+                def mk(orig):
+                    def wrapper(self, *a, **k):
+                        _enforce(hook, "openai-agents", str(getattr(self, "name", "tool")))
+                        return orig(self, *a, **k)
+                    return wrapper
+                ok = _wrap(FunctionTool, meth, mk) or ok
+        return ok
+
+
+# ── MCP servers ───────────────────────────────────────────────────────────────
+
+class MCPDetector(Detector):
+    framework = "mcp"
+    module_hint = "mcp"
+
+    def instrument(self, hook, on_discover):
+        ok = False
+        # FastMCP tool calls
+        try:
+            from mcp.server.fastmcp import FastMCP
+            for meth in ("call_tool",):
+                def mk(orig):
+                    def wrapper(self, name, *a, **k):
+                        try:
+                            on_discover(AgentInfo(name=str(name), framework="mcp", kind="mcp_server"))
+                        except Exception:
+                            pass
+                        _enforce(hook, "mcp", str(name))
+                        return orig(self, name, *a, **k)
+                    return wrapper
+                ok = _wrap(FastMCP, meth, mk) or ok
+        except Exception:
+            pass
+        # Low-level server
+        try:
+            from mcp.server import Server
+            for meth in ("call_tool",):
+                def mk(orig):
+                    def wrapper(self, *a, **k):
+                        _enforce(hook, "mcp", "call_tool")
+                        return orig(self, *a, **k)
+                    return wrapper
+                ok = _wrap(Server, meth, mk) or ok
+        except Exception:
+            pass
+        return ok
+
+
+# ── LangGraph ─────────────────────────────────────────────────────────────────
+
+class LangGraphDetector(Detector):
+    framework = "langgraph"
+    module_hint = "langgraph"
+
+    def instrument(self, hook, on_discover):
+        ok = False
+        try:
+            from langgraph.graph import StateGraph
+
+            def mk(orig):
+                def wrapper(self, node, *a, **k):
+                    try:
+                        on_discover(AgentInfo(name=str(node), framework="langgraph", kind="workflow"))
+                    except Exception:
+                        pass
+                    return orig(self, node, *a, **k)
+                return wrapper
+            ok = _wrap(StateGraph, "add_node", mk) or ok
+        except Exception:
+            pass
+        return ok
+
+
+# ── AutoGen ───────────────────────────────────────────────────────────────────
+
+class AutoGenDetector(Detector):
+    framework = "autogen"
+    module_hint = "autogen"
+
+    def instrument(self, hook, on_discover):
+        ok = False
+        try:
+            import autogen
+            CA = getattr(autogen, "ConversableAgent", None)
+            if CA is not None:
+                def mk_init(orig):
+                    def wrapper(self, *a, **k):
+                        orig(self, *a, **k)
+                        try:
+                            on_discover(AgentInfo(name=str(getattr(self, "name", "autogen-agent")),
+                                                  framework="autogen", kind="agent"))
+                        except Exception:
+                            pass
+                    return wrapper
+                ok = _wrap(CA, "__init__", mk_init) or ok
+
+                def mk(orig):
+                    def wrapper(self, *a, **k):
+                        _enforce(hook, "autogen", "execute_function",
+                                 agent=str(getattr(self, "name", "autogen-agent")))
+                        return orig(self, *a, **k)
+                    return wrapper
+                for meth in ("execute_function",):
+                    ok = _wrap(CA, meth, mk) or ok
+        except Exception:
+            pass
+        return ok
+
+
+# ── Semantic Kernel ─────────────────────────────────────────────────────────
+
+class SemanticKernelDetector(Detector):
+    framework = "semantic-kernel"
+    module_hint = "semantic_kernel"
+
+    def instrument(self, hook, on_discover):
+        ok = False
+        try:
+            from semantic_kernel.functions.kernel_function import KernelFunction
+            for meth in ("invoke", "__call__"):
+                def mk(orig):
+                    def wrapper(self, *a, **k):
+                        name = getattr(self, "name", None) or getattr(self, "fully_qualified_name", "kernel-function")
+                        try:
+                            on_discover(AgentInfo(name=str(name), framework="semantic-kernel", kind="tool"))
+                        except Exception:
+                            pass
+                        _enforce(hook, "semantic-kernel", str(name))
+                        return orig(self, *a, **k)
+                    return wrapper
+                ok = _wrap(KernelFunction, meth, mk) or ok
+        except Exception:
+            pass
+        return ok
+
+
+# ── LlamaIndex ────────────────────────────────────────────────────────────────
+
+class LlamaIndexDetector(Detector):
+    framework = "llamaindex"
+    module_hint = "llama_index"
+
+    def instrument(self, hook, on_discover):
+        ok = False
+        try:
+            from llama_index.core.tools import FunctionTool
+            for meth in ("call", "__call__", "acall"):
+                def mk(orig):
+                    def wrapper(self, *a, **k):
+                        meta = getattr(self, "metadata", None)
+                        name = getattr(meta, "name", None) if meta else "llamaindex-tool"
+                        try:
+                            on_discover(AgentInfo(name=str(name), framework="llamaindex", kind="tool"))
+                        except Exception:
+                            pass
+                        _enforce(hook, "llamaindex", str(name))
+                        return orig(self, *a, **k)
+                    return wrapper
+                ok = _wrap(FunctionTool, meth, mk) or ok
+        except Exception:
+            pass
+        return ok
+
+
+# ── Generic: FastAPI + Celery presence (deep hooks land in a later pass) ──────
+
+class FastAPIDetector(Detector):
+    framework = "fastapi"
+    module_hint = "fastapi"
+
+
+class CeleryDetector(Detector):
+    framework = "celery"
+    module_hint = "celery"
+
+
+def build() -> List[Detector]:
+    return [
+        LangChainDetector(), CrewAIDetector(), OpenAIAgentsDetector(), MCPDetector(),
+        LangGraphDetector(), AutoGenDetector(), SemanticKernelDetector(), LlamaIndexDetector(),
+        FastAPIDetector(), CeleryDetector(),
+    ]
+
+
+def _firststr(args, kwargs, limit: int = 2000):
+    for v in list(args) + list(kwargs.values()):
+        if isinstance(v, str):
+            return v[:limit]
+    return None

xybern/exceptions.py

@@ -0,0 +1,21 @@
+"""Xybern SDK exceptions."""
+
+
+class XybernError(Exception):
+    pass
+
+
+class PolicyBlocked(XybernError):
+    """Raised when an action is blocked by an enforced policy."""
+    def __init__(self, action_type: str, reason: str = ""):
+        self.action_type = action_type
+        self.reason = reason
+        super().__init__(f"Xybern blocked action '{action_type}'" + (f": {reason}" if reason else ""))
+
+
+class PolicyEscalated(XybernError):
+    """Raised when an action requires human approval before it can proceed."""
+    def __init__(self, action_type: str, escalation_id: str = ""):
+        self.action_type = action_type
+        self.escalation_id = escalation_id
+        super().__init__(f"Xybern escalated action '{action_type}' for human review")

xybern/telemetry.py

@@ -0,0 +1,52 @@
+"""Async, fail-open telemetry for OBSERVE mode.
+
+In observe mode every intercepted action is enqueued and flushed in batches to the
+control plane (decisions are recorded server-side; the SDK never blocks). The queue
+is bounded and lossy under pressure — telemetry must never slow down or crash the
+host agent.
+"""
+
+from __future__ import annotations
+
+import queue
+import threading
+from typing import Any, Dict
+
+
+class Telemetry:
+    def __init__(self, client, config, batch_size: int = 50, flush_interval: float = 2.0):
+        self.client = client
+        self.cfg = config
+        self.batch_size = batch_size
+        self.flush_interval = flush_interval
+        self._q: "queue.Queue[Dict[str, Any]]" = queue.Queue(maxsize=10000)
+        self._started = False
+
+    def start(self):
+        if self._started or not self.cfg.authenticated:
+            return
+        self._started = True
+        threading.Thread(target=self._loop, daemon=True, name="xybern-telemetry").start()
+
+    def record(self, event: Dict[str, Any]):
+        try:
+            self._q.put_nowait(event)
+        except queue.Full:
+            pass  # drop under pressure — never block the agent
+
+    def _loop(self):
+        batch = []
+        while True:
+            try:
+                batch.append(self._q.get(timeout=self.flush_interval))
+            except queue.Empty:
+                pass
+            if batch and (len(batch) >= self.batch_size or self._q.empty()):
+                self._flush(batch)
+                batch = []
+
+    def _flush(self, batch):
+        try:
+            self.client.batch_intercept(batch)
+        except Exception:
+            pass  # fail-open: a telemetry outage must not affect the host

xybern-2.0.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: xybern
+Version: 2.0.0
+Summary: Identity & authorisation infrastructure for AI agents — install once, discover every agent, authorise every action.
+Author-email: Xybern <info@xybern.com>
+License: MIT
+Project-URL: Homepage, https://www.xybern.com
+Project-URL: Documentation, https://docs.xybern.com/authorization/sdk
+Keywords: ai,agents,authorization,identity,governance,langchain,crewai,mcp,provenance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41.0.0; extra == "crypto"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# Xybern
+
+**Identity & authorisation infrastructure for AI agents.** Install once — Xybern
+discovers every AI agent in your system, gives each a cryptographic identity, and
+(when you turn enforcement on) authorises every action *before* it executes.
+
+```bash
+pip install xybern
+xybern login          # browser device-code flow (auto-links your workspace)
+```
+
+```python
+from xybern import auto
+auto.connect()        # discovers frameworks + agents + tools, registers them, instruments them
+```
+
+```
+✓ Detected frameworks: CrewAI, LangGraph, 2 MCP servers
+✓ Found 12 agents · 48 tools
+✓ Registered to workspace "Acme Corp" (each issued a cryptographic identity)
+✓ Mode: OBSERVE — actions logged, nothing blocked yet
+```
+
+## What it does
+
+- **Auto-discovery** — detects and instruments LangChain, CrewAI, OpenAI Agents SDK,
+  MCP servers, LangGraph, AutoGen, Semantic Kernel, LlamaIndex (and FastAPI/Celery).
+  No manual wiring; agents appear in your Xybern dashboard as your app creates them.
+- **Cryptographic identity** — every discovered agent is registered and issued an
+  identity, so its actions are attributable and signable.
+- **Authorisation before execution** — each tool/agent action passes through Xybern's
+  policy engine; `allow` / `block` / `escalate`.
+- **Observe-first & fail-open** — default mode only *logs* (never blocks). When you
+  switch to enforce, the SDK fails open if Xybern is unreachable, so it can't take
+  your agents down.
+- **Privacy** — sends content **hashes** by default, not raw payloads.
+
+## Modes
+
+```python
+auto.connect()                 # OBSERVE (default): log + inventory, never blocks
+auto.connect(mode="enforce")   # authorise actions (allow/block/escalate)
+```
+or persist it: `xybern enforce on` / `xybern enforce off`.
+
+## CLI
+
+```
+xybern login [--api-key xb_...]   # device-code flow, or paste a key / set XYBERN_API_KEY
+xybern agents                     # dry-run: what would be discovered
+xybern status
+xybern enforce on|off
+xybern logout
+```
+
+## Auth options
+
+1. **Device code** — `xybern login` opens a browser; approve + pick a workspace; a
+   scoped key is minted and stored in `~/.xybern/credentials.json`.
+2. **API key** — `xybern login --api-key xb_...`, or `export XYBERN_API_KEY=xb_...`,
+   or `auto.connect(api_key="xb_...")`.
+
+## Configuration
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `observe` | `observe` (log only) or `enforce` (act on decisions) |
+| `fail_open` | `True` | allow actions through if Xybern is unreachable (enforce mode) |
+| `redact` | `True` | send content hashes instead of raw content |
+| `frameworks` | all | restrict to specific frameworks |
+
+Docs: https://docs.xybern.com/authorization/sdk

xybern-2.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+xybern/__init__.py,sha256=nxrIqGsOgmvHqtczfNK11U3uLihGCfgkPEAb5aabRG4,900
+xybern/auto.py,sha256=23m3SKxcnRD5jFwpcIDpMoUXbaFiH4SaDGz1Zp56ZQs,6150
+xybern/client.py,sha256=wUFwAXPd5gIni4PcKfe9GX3o1vUUu54kaBQ1YCjGXSY,4101
+xybern/config.py,sha256=C7NYFQueJPHnM8NFN2cv8zkyF7lH0rgyjl0yRsPlc_E,3161
+xybern/exceptions.py,sha256=a7z4TbXcrRnFXDLHj9drirbppS9_3gqcz6t1cL045r0,755
+xybern/telemetry.py,sha256=y7i-W2-C6b4elVvptJfm9jRzli-A3Bwh4BzNO9OPbOs,1703
+xybern/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xybern/cli/__main__.py,sha256=E0baJXPUsl46TLI6SePv6czIe_z56HwmDrSbVNstqo4,5766
+xybern/discovery/__init__.py,sha256=5PIPdy42m6n2pctoW5VD8t4mXRayPSN4VO0u2zhsaRQ,3775
+xybern/discovery/detectors.py,sha256=dd0iuNi6TlPaZuR9gGakimAE_UxUBGk2Wg2GzYiw6OU,13641
+xybern-2.0.0.dist-info/METADATA,sha256=DDdYvt95jaESmYCmIhBdsxDRsTmvrc8zuDnSaa5ofJs,3386
+xybern-2.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+xybern-2.0.0.dist-info/entry_points.txt,sha256=80JV-7qZiC55cjgBSO9tzpsVgZlOwyzvUHEkyE3YNTs,52
+xybern-2.0.0.dist-info/top_level.txt,sha256=VjRinkGTjBhdhPoKoZAk521u6oOVLYFvkoFlWT_umPY,7
+xybern-2.0.0.dist-info/RECORD,,

xybern-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xybern-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+xybern = xybern.cli.__main__:main

xybern-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xybern