spanforge 1.0.0__py3-none-any.whl

spanforge/_cli_phase11.py

@@ -0,0 +1,356 @@
+"""Phase 11 enterprise and security command groups for the SpanForge CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def add_phase11_subcommands(
+    sub: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> tuple[argparse.ArgumentParser, argparse.ArgumentParser]:
+    """Register enterprise and security CLI subcommands."""
+    enterprise_parser = sub.add_parser(
+        "enterprise",
+        help="Enterprise hardening & multi-tenancy operations",
+    )
+    enterprise_sub = enterprise_parser.add_subparsers(
+        dest="enterprise_command",
+        metavar="<action>",
+    )
+
+    enterprise_sub.add_parser(
+        "status",
+        help="Show enterprise hardening status",
+    ).add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    ent_reg = enterprise_sub.add_parser(
+        "register-tenant",
+        help="Register a project tenant with isolation config",
+    )
+    ent_reg.add_argument("--project-id", required=True, metavar="ID", help="Project identifier")
+    ent_reg.add_argument("--org-id", required=True, metavar="ID", help="Organisation identifier")
+    ent_reg.add_argument(
+        "--residency",
+        default="global",
+        choices=["eu", "us", "ap", "in", "global"],
+        help="Data residency region (default: global)",
+    )
+
+    enterprise_sub.add_parser(
+        "list-tenants",
+        help="List all registered tenants",
+    ).add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    enterprise_sub.add_parser(
+        "encrypt-config",
+        help="Show current encryption configuration",
+    )
+
+    enterprise_sub.add_parser(
+        "health",
+        help="Run health checks on all SpanForge services",
+    ).add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    security_parser = sub.add_parser(
+        "security",
+        help="Security review & supply-chain scanning",
+    )
+    security_sub = security_parser.add_subparsers(
+        dest="security_command",
+        metavar="<action>",
+    )
+
+    security_sub.add_parser(
+        "owasp",
+        help="Run OWASP API Security Top 10 audit",
+    ).add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    security_sub.add_parser(
+        "threat-model",
+        help="Generate default STRIDE threat model",
+    ).add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    security_sub.add_parser(
+        "scan",
+        help="Run full security scan (deps + static + secrets)",
+    ).add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    sec_audit = security_sub.add_parser(
+        "audit-logs",
+        help="Check log file for leaked secrets",
+    )
+    sec_audit.add_argument(
+        "--file",
+        default=None,
+        metavar="PATH",
+        help="Path to log file to audit",
+    )
+
+    return enterprise_parser, security_parser
+
+
+def dispatch_phase11_command(
+    args: argparse.Namespace,
+    enterprise_parser: argparse.ArgumentParser,
+    security_parser: argparse.ArgumentParser,
+) -> int | None:
+    """Dispatch enterprise or security commands when selected."""
+    command = getattr(args, "command", None)
+    if command == "enterprise":
+        return _cmd_enterprise(args, enterprise_parser)
+    if command == "security":
+        return _cmd_security(args, security_parser)
+    return None
+
+
+def _cmd_enterprise(
+    args: argparse.Namespace,
+    enterprise_parser: argparse.ArgumentParser,
+) -> int:
+    """Handle ``spanforge enterprise`` subcommands."""
+    action = getattr(args, "enterprise_command", None)
+
+    if action == "status":
+        return _cmd_enterprise_status(args)
+    if action == "register-tenant":
+        return _cmd_enterprise_register_tenant(args)
+    if action == "list-tenants":
+        return _cmd_enterprise_list_tenants(args)
+    if action == "encrypt-config":
+        return _cmd_enterprise_encrypt_config(args)
+    if action == "health":
+        return _cmd_enterprise_health(args)
+
+    enterprise_parser.print_help()
+    return 2
+
+
+def _cmd_enterprise_status(args: argparse.Namespace) -> int:
+    """``spanforge enterprise status`` - show enterprise hardening status."""
+    from spanforge.sdk import sf_enterprise
+
+    status = sf_enterprise.get_status()
+    fmt = getattr(args, "format", "text")
+
+    if fmt == "json":
+        import dataclasses
+
+        print(json.dumps(dataclasses.asdict(status), indent=2, default=str))
+    else:
+        print("Enterprise Hardening Status")
+        print(f"  Multi-Tenancy: {'enabled' if status.multi_tenancy_enabled else 'disabled'}")
+        print(f"  Tenants:       {status.tenant_count}")
+        print(f"  Encryption:    {'at-rest' if status.encryption_at_rest else 'off'}")
+        print(f"  FIPS Mode:     {'on' if status.fips_mode else 'off'}")
+        print(f"  Offline Mode:  {'on' if status.offline_mode else 'off'}")
+        print(f"  Residency:     {status.data_residency}")
+    return 0
+
+
+def _cmd_enterprise_register_tenant(args: argparse.Namespace) -> int:
+    """``spanforge enterprise register-tenant`` - register a new tenant."""
+    from spanforge.sdk import sf_enterprise
+
+    tenant = sf_enterprise.register_tenant(
+        project_id=args.project_id,
+        org_id=args.org_id,
+        data_residency=getattr(args, "residency", "global"),
+    )
+    print(f"[✓] Tenant registered: project={tenant.project_id} org={tenant.org_id}")
+    print(f"  Residency: {tenant.data_residency}")
+    return 0
+
+
+def _cmd_enterprise_list_tenants(args: argparse.Namespace) -> int:
+    """``spanforge enterprise list-tenants`` - list registered tenants."""
+    from spanforge.sdk import sf_enterprise
+
+    tenants = sf_enterprise.list_tenants()
+    fmt = getattr(args, "format", "text")
+
+    if fmt == "json":
+        import dataclasses
+
+        print(json.dumps([dataclasses.asdict(t) for t in tenants], indent=2, default=str))
+    elif not tenants:
+        print("No tenants registered.")
+    else:
+        for tenant in tenants:
+            print(
+                f"  {tenant.project_id} (org={tenant.org_id}, residency={tenant.data_residency})"
+            )
+    return 0
+
+
+def _cmd_enterprise_encrypt_config(_args: argparse.Namespace) -> int:
+    """``spanforge enterprise encrypt-config`` - show encryption settings."""
+    from spanforge.sdk import sf_enterprise
+
+    enc = sf_enterprise.get_encryption_config()
+    import dataclasses
+
+    print(json.dumps(dataclasses.asdict(enc), indent=2, default=str))
+    return 0
+
+
+def _cmd_enterprise_health(args: argparse.Namespace) -> int:
+    """``spanforge enterprise health`` - run health checks on all services."""
+    from spanforge.sdk import sf_enterprise
+
+    results = sf_enterprise.check_all_services_health()
+    fmt = getattr(args, "format", "text")
+
+    if fmt == "json":
+        import dataclasses
+
+        print(json.dumps([dataclasses.asdict(result) for result in results], indent=2, default=str))
+    else:
+        all_ok = all(result.ok for result in results)
+        for result in results:
+            marker = "✓" if result.ok else "✗"
+            print(
+                f"  [{marker}] {result.service}{result.endpoint} - "
+                f"{result.status} ({result.latency_ms:.1f}ms)"
+            )
+        print()
+        print(f"Overall: {'HEALTHY' if all_ok else 'DEGRADED'}")
+    return 0
+
+
+def _cmd_security(
+    args: argparse.Namespace,
+    security_parser: argparse.ArgumentParser,
+) -> int:
+    """Handle ``spanforge security`` subcommands."""
+    action = getattr(args, "security_command", None)
+
+    if action == "owasp":
+        return _cmd_security_owasp(args)
+    if action == "threat-model":
+        return _cmd_security_threat_model(args)
+    if action == "scan":
+        return _cmd_security_scan(args)
+    if action == "audit-logs":
+        return _cmd_security_audit_logs(args)
+
+    security_parser.print_help()
+    return 2
+
+
+def _cmd_security_owasp(args: argparse.Namespace) -> int:
+    """``spanforge security owasp`` - run OWASP API Security audit."""
+    from spanforge.sdk import sf_security
+
+    result = sf_security.run_owasp_audit()
+    fmt = getattr(args, "format", "text")
+
+    if fmt == "json":
+        import dataclasses
+
+        print(json.dumps(dataclasses.asdict(result), indent=2, default=str))
+    else:
+        verdict = "PASS" if result.pass_ else "FAIL"
+        print(f"OWASP API Security Top 10 Audit: {verdict}")
+        for cat_id, info in result.categories.items():
+            marker = "✓" if info["status"] == "pass" else "✗"
+            print(f"  [{marker}] {cat_id}: {info['name']}")
+            if info.get("detail"):
+                print(f"       {info['detail']}")
+    return 0 if result.pass_ else 1
+
+
+def _cmd_security_threat_model(args: argparse.Namespace) -> int:
+    """``spanforge security threat-model`` - generate default STRIDE threat model."""
+    from spanforge.sdk import sf_security
+
+    entries = sf_security.generate_default_threat_model()
+    fmt = getattr(args, "format", "text")
+
+    if fmt == "json":
+        import dataclasses
+
+        print(json.dumps([dataclasses.asdict(entry) for entry in entries], indent=2, default=str))
+    else:
+        print(f"STRIDE Threat Model ({len(entries)} entries):")
+        for entry in entries:
+            print(f"  [{entry.risk_level.upper()}] {entry.service} / {entry.category}")
+            print(f"    Threat:     {entry.threat}")
+            print(f"    Mitigation: {entry.mitigation}")
+    return 0
+
+
+def _cmd_security_scan(args: argparse.Namespace) -> int:
+    """``spanforge security scan`` - run full security scan."""
+    from spanforge.sdk import sf_security
+
+    result = sf_security.run_full_scan()
+    fmt = getattr(args, "format", "text")
+
+    if fmt == "json":
+        import dataclasses
+
+        print(json.dumps(dataclasses.asdict(result), indent=2, default=str))
+    else:
+        verdict = "PASS" if result.pass_ else "FAIL"
+        print(f"Security Scan: {verdict}")
+        print(f"  Vulnerabilities:     {len(result.vulnerabilities)}")
+        print(f"  Static findings:     {len(result.static_findings)}")
+        print(f"  Secrets in logs:     {result.secrets_in_logs}")
+    return 0 if result.pass_ else 1
+
+
+def _cmd_security_audit_logs(args: argparse.Namespace) -> int:
+    """``spanforge security audit-logs`` - check logs for leaked secrets."""
+    from spanforge.sdk import sf_security
+
+    log_file = getattr(args, "file", None)
+    if not log_file:
+        print("[✓] No log file specified - clean.")
+        return 0
+
+    try:
+        with open(log_file, encoding="utf-8") as fh:
+            lines = fh.readlines()
+    except OSError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    count = sf_security.audit_logs_for_secrets_safe(lines)
+    if count:
+        print(f"[✗] Found {count} secret(s) in log output!")
+        return 1
+
+    print("[✓] No secrets detected in logs.")
+    return 0

spanforge/_hooks.py

@@ -0,0 +1,337 @@
+"""spanforge._hooks — Global span lifecycle hook registry.
+
+Provides a :class:`HookRegistry` for registering callbacks that fire when
+spans of specific operation types start or end.  A module-level singleton
+``hooks`` is exported from ``spanforge.__init__`` for convenience.
+
+Usage — synchronous hooks::
+
+    import spanforge
+
+    @spanforge.hooks.on_llm_call
+    def log_llm(span) -> None:
+        print(f"LLM call started: {span.name!r} model={span.model!r}")
+
+    @spanforge.hooks.on_agent_end
+    def audit_agent(span) -> None:
+        if span.status == "error":
+            alert(f"Agent error: {span.error}")
+
+Usage — async hooks (for async-first applications)::
+
+    @spanforge.hooks.on_llm_call_async
+    async def async_log_llm(span) -> None:
+        await db.log_span(span.span_id, span.model)
+
+Hook callbacks receive the :class:`~spanforge._span.Span` object.  Start
+hooks fire in ``SpanContextManager.__enter__`` (before the body executes);
+end hooks fire in ``SpanContextManager.__exit__`` (after the body, before
+export).
+
+**Thread safety**: ``HookRegistry`` uses a ``threading.RLock`` so hooks can
+be registered from any thread.  Synchronous hook *callbacks* are called on
+whatever thread the span context manager runs on.  Async hook callbacks are
+scheduled via :func:`asyncio.ensure_future` if a loop is running, otherwise
+they are silently skipped.
+
+**Error isolation**: if a hook raises an exception the error is suppressed
+(emitted via ``warnings.warn``) so that hook failures never abort user code.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import inspect
+import threading
+import warnings
+from collections.abc import Coroutine
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from spanforge._span import Span
+
+__all__ = ["HookFn", "HookRegistry", "hooks"]
+
+# ---------------------------------------------------------------------------
+# Type aliases
+# ---------------------------------------------------------------------------
+
+HookFn = Callable[["Span"], None]
+AsyncHookFn = Callable[["Span"], Coroutine[Any, Any, None]]
+
+# Hook kind constants — match the operation strings used in SpanPayload.
+_HOOK_AGENT_START = "agent_start"
+_HOOK_AGENT_END = "agent_end"
+_HOOK_LLM_CALL = "llm_call"
+_HOOK_TOOL_CALL = "tool_call"
+
+# Map span operation values → hook kind (for "start" hooks the same mapping is
+# used; the distinction between start and end is made by the context manager).
+_LLM_OPERATIONS = frozenset({"chat", "completion", "embedding", "chat_completion", "generate"})
+_TOOL_OPERATIONS = frozenset({"tool_call", "execute_tool"})
+_AGENT_OPERATIONS = frozenset({"invoke_agent", "agent"})
+
+
+def _classify_span(span: Span) -> str | None:
+    """Return the hook kind for *span*, or ``None`` if no hook applies."""
+    op = str(getattr(span, "operation", "") or "")
+    if op in _LLM_OPERATIONS or op == "chat":
+        return _HOOK_LLM_CALL
+    if op in _TOOL_OPERATIONS:
+        return _HOOK_TOOL_CALL
+    if op in _AGENT_OPERATIONS:
+        return _HOOK_AGENT_START  # caller differentiates start/end
+    # Fallback: if the span name contains a hint use that.
+    name = str(getattr(span, "name", "") or "")
+    if "llm" in name.lower() or "model" in name.lower():
+        return _HOOK_LLM_CALL
+    if "tool" in name.lower():
+        return _HOOK_TOOL_CALL
+    return None
+
+
+# ---------------------------------------------------------------------------
+# HookRegistry
+# ---------------------------------------------------------------------------
+
+
+class HookRegistry:
+    """Registry of span lifecycle hooks.
+
+    Each ``on_*`` method can be used as a **decorator** or called directly
+    to register a callback:
+
+    .. code-block:: python
+
+        @hooks.on_llm_call
+        def my_hook(span): ...
+
+        # equivalent:
+        hooks.on_llm_call(my_hook)
+
+    Methods:
+        on_agent_start: Register a callback fired when any agent-operation span **starts**.
+        on_agent_end:   Register a callback fired when any agent-operation span **ends**.
+        on_llm_call:    Register a callback fired at both start and end of LLM spans.
+        on_tool_call:   Register a callback fired at both start and end of tool spans.
+        clear:          Remove all registered hooks.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._hooks: dict[str, list[HookFn]] = {
+            _HOOK_AGENT_START: [],
+            _HOOK_AGENT_END: [],
+            _HOOK_LLM_CALL: [],
+            _HOOK_TOOL_CALL: [],
+        }
+        self._async_hooks: dict[str, list[AsyncHookFn]] = {
+            _HOOK_AGENT_START: [],
+            _HOOK_AGENT_END: [],
+            _HOOK_LLM_CALL: [],
+            _HOOK_TOOL_CALL: [],
+        }
+        # Universal span-end hooks: fire for EVERY span regardless of operation.
+        self._all_end_hooks: list[HookFn] = []
+
+    # ------------------------------------------------------------------
+    # Registration decorators / methods
+    # ------------------------------------------------------------------
+
+    def on_agent_start(self, fn: HookFn) -> HookFn:
+        """Register *fn* to fire when an agent-operation span **starts**.
+
+        Can be used as a decorator::
+
+            @hooks.on_agent_start
+            def cb(span): ...
+        """
+        with self._lock:
+            self._hooks[_HOOK_AGENT_START].append(fn)
+        return fn
+
+    def on_agent_end(self, fn: HookFn) -> HookFn:
+        """Register *fn* to fire when an agent-operation span **ends**."""
+        with self._lock:
+            self._hooks[_HOOK_AGENT_END].append(fn)
+        return fn
+
+    def on_llm_call(self, fn: HookFn) -> HookFn:
+        """Register *fn* to fire on LLM-operation spans (start **and** end)."""
+        with self._lock:
+            self._hooks[_HOOK_LLM_CALL].append(fn)
+        return fn
+
+    def on_tool_call(self, fn: HookFn) -> HookFn:
+        """Register *fn* to fire on tool-call spans (start **and** end)."""
+        with self._lock:
+            self._hooks[_HOOK_TOOL_CALL].append(fn)
+        return fn
+
+    def on_span_end(self, fn: HookFn) -> HookFn:
+        """Register *fn* to fire when **any** span ends, regardless of operation type.
+
+        Unlike :meth:`on_agent_end`, :meth:`on_llm_call`, and :meth:`on_tool_call`
+        which only fire for operation-classified spans, this hook fires for every
+        :class:`~spanforge._span.Span` that exits via :class:`~spanforge._span.SpanContextManager`.
+
+        Primary use case: collecting all spans in test code via the
+        :func:`~spanforge.testing.captured_spans` pytest fixture.
+
+        Can be used as a decorator::
+
+            @hooks.on_span_end
+            def cb(span): ...
+        """
+        with self._lock:
+            self._all_end_hooks.append(fn)
+        return fn
+
+    # ------------------------------------------------------------------
+    # Async registration decorators / methods
+    # ------------------------------------------------------------------
+
+    def on_agent_start_async(self, fn: AsyncHookFn) -> AsyncHookFn:
+        """Register an **async** callback to fire when an agent span **starts**.
+
+        The coroutine is scheduled via :func:`asyncio.ensure_future` when a
+        running event loop is detected.  If no loop is running the callback is
+        silently skipped.
+
+        Can be used as a decorator::
+
+            @hooks.on_agent_start_async
+            async def cb(span): await db.record_start(span.span_id)
+        """
+        with self._lock:
+            self._async_hooks[_HOOK_AGENT_START].append(fn)
+        return fn
+
+    def on_agent_end_async(self, fn: AsyncHookFn) -> AsyncHookFn:
+        """Register an **async** callback to fire when an agent span **ends**."""
+        with self._lock:
+            self._async_hooks[_HOOK_AGENT_END].append(fn)
+        return fn
+
+    def on_llm_call_async(self, fn: AsyncHookFn) -> AsyncHookFn:
+        """Register an **async** callback to fire on LLM spans (start **and** end)."""
+        with self._lock:
+            self._async_hooks[_HOOK_LLM_CALL].append(fn)
+        return fn
+
+    def on_tool_call_async(self, fn: AsyncHookFn) -> AsyncHookFn:
+        """Register an **async** callback to fire on tool-call spans (start **and** end)."""
+        with self._lock:
+            self._async_hooks[_HOOK_TOOL_CALL].append(fn)
+        return fn
+
+    def clear(self) -> None:
+        """Unregister all synchronous, async, and universal hooks."""
+        with self._lock:
+            for key in self._hooks:
+                self._hooks[key].clear()
+            for key in self._async_hooks:
+                self._async_hooks[key].clear()
+            self._all_end_hooks.clear()
+
+    # ------------------------------------------------------------------
+    # Internal fire helpers (called by SpanContextManager)
+    # ------------------------------------------------------------------
+
+    def _fire_start(self, span: Span) -> None:
+        """Fire the appropriate start hooks for *span*."""
+        kind = _classify_span(span)
+        if kind is None:
+            return
+        if kind in (_HOOK_LLM_CALL, _HOOK_TOOL_CALL):
+            self._fire(kind, span)
+        elif kind == _HOOK_AGENT_START:
+            self._fire(_HOOK_AGENT_START, span)
+
+    def _fire_end(self, span: Span) -> None:
+        """Fire the appropriate end hooks for *span*, plus universal span-end hooks."""
+        kind = _classify_span(span)
+        if kind is not None:
+            if kind in (_HOOK_LLM_CALL, _HOOK_TOOL_CALL):
+                self._fire(kind, span)
+            elif kind == _HOOK_AGENT_START:
+                # Re-use agent_end bucket for end hooks.
+                self._fire(_HOOK_AGENT_END, span)
+        # Always fire universal span-end hooks regardless of classification.
+        self._fire_all_end(span)
+
+    def _fire_all_end(self, span: Span) -> None:
+        """Fire all universal span-end hooks registered via :meth:`on_span_end`."""
+        with self._lock:
+            callbacks = list(self._all_end_hooks)
+        for cb in callbacks:
+            try:
+                cb(span)
+            except Exception as exc:
+                with contextlib.suppress(Exception):
+                    warnings.warn(
+                        f"spanforge on_span_end hook error in {cb!r}: {exc}",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+
+    def _fire(self, kind: str, span: Span) -> None:
+        with self._lock:
+            callbacks = list(self._hooks.get(kind, []))
+        for cb in callbacks:
+            try:
+                cb(span)
+            except Exception as exc:
+                with contextlib.suppress(Exception):
+                    warnings.warn(
+                        f"spanforge hook error in {cb!r}: {exc}",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+        # Fire async hooks if a loop is running.
+        self._fire_async(kind, span)
+
+    def _fire_async(self, kind: str, span: Span) -> None:
+        """Schedule async hook coroutines on the running event loop (if any)."""
+        with self._lock:
+            async_callbacks = list(self._async_hooks.get(kind, []))
+        if not async_callbacks:
+            return
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return  # no event loop running — skip async hooks silently
+        for cb in async_callbacks:
+            try:
+                coro = cb(span)
+                if inspect.isawaitable(coro):
+                    _task = asyncio.ensure_future(coro, loop=loop)
+                    _task.add_done_callback(lambda t: None)
+            except Exception as exc:
+                with contextlib.suppress(Exception):
+                    warnings.warn(
+                        f"spanforge async hook error in {cb!r}: {exc}",
+                        UserWarning,
+                        stacklevel=2,
+                    )
+
+    def __repr__(self) -> str:
+        with self._lock:
+            counts = {k: len(v) for k, v in self._hooks.items()}
+            async_counts = {k: len(v) for k, v in self._async_hooks.items()}
+        return f"HookRegistry(sync={counts}, async={async_counts})"
+
+
+# ---------------------------------------------------------------------------
+# Module-level singleton
+# ---------------------------------------------------------------------------
+
+hooks: HookRegistry = HookRegistry()
+"""Global singleton :class:`HookRegistry` — import and use directly::
+
+    from spanforge import hooks
+
+    @hooks.on_llm_call
+    def my_callback(span): ...
+"""