superuser 0.1.0__py3-none-any.whl

superuser/__init__.py

@@ -0,0 +1,5 @@
+"""Superuser: a permission-gated sysadmin MCP agent with Cisco AI Defense guardrails."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

superuser/__main__.py

@@ -0,0 +1,62 @@
+"""Entry point: `superuser` / `python -m superuser`."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from .config import Config
+from .server import build_server
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="superuser",
+        description="Permission-gated superuser MCP agent with Cisco AI Defense guardrails.",
+    )
+    parser.add_argument("--config", help="Path to a YAML config file (or set SUPERUSER_CONFIG).")
+    parser.add_argument(
+        "--transport", default="stdio", choices=["stdio", "sse", "streamable-http"],
+        help="MCP transport (default: stdio).",
+    )
+    parser.add_argument("--log-level", default="INFO")
+    parser.add_argument(
+        "--check", action="store_true",
+        help="Validate config and print security status, then exit (no server).",
+    )
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    config = Config.load(args.config)
+    server = build_server(config)
+
+    if args.check:
+        from .authz import DuoAuthorizer
+        from .billing import StripeMeter
+        from .security import CiscoAIDefense
+
+        defense = CiscoAIDefense(config.cisco)
+        authorizer = DuoAuthorizer(config.duo)
+        meter = StripeMeter(config.stripe)
+        print("Superuser agent configuration OK.")
+        print(f"  Human owner:          {config.human_owner}")
+        print(f"  Approval required at: {config.approval_required_at.name}")
+        print(f"  Audit log:            {config.audit_log_path}")
+        print(f"  Cisco AI Defense:     {defense.status}")
+        print(f"  Cisco Duo (authz):    {authorizer.status}")
+        print(f"  Stripe billing:       {meter.status}")
+        print(f"  GitHub configured:    {bool(config.github.token)}")
+        return 0
+
+    server.run(transport=args.transport)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

superuser/audit.py

@@ -0,0 +1,70 @@
+"""Append-only audit logging.
+
+Every tool invocation produces an identity-correlated record:
+``human owner -> agent -> tool -> action -> outcome``. This is the local
+counterpart to the audit chain enforced by Cisco Duo's MCP gateway, and it is
+what makes the agent's actions reviewable after the fact.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# Argument keys whose values must never be written to the audit log verbatim.
+_SENSITIVE_KEYS = {"token", "api_key", "apikey", "password", "secret", "authorization"}
+
+
+def _redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            k: ("***REDACTED***" if k.lower() in _SENSITIVE_KEYS else _redact(v))
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [_redact(v) for v in value]
+    if isinstance(value, str) and len(value) > 2000:
+        return value[:2000] + f"...[truncated {len(value) - 2000} chars]"
+    return value
+
+
+class AuditLog:
+    """Thread-safe JSONL audit logger."""
+
+    def __init__(self, path: str | os.PathLike[str], human_owner: str = "unknown") -> None:
+        self.path = Path(path)
+        self.human_owner = human_owner
+        self._lock = threading.Lock()
+        if self.path.parent and not self.path.parent.exists():
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def record(
+        self,
+        tool: str,
+        arguments: dict[str, Any],
+        decision: str,
+        status: str,
+        *,
+        risk: str | None = None,
+        detail: str | None = None,
+    ) -> dict[str, Any]:
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "human_owner": self.human_owner,
+            "agent": "superuser",
+            "tool": tool,
+            "arguments": _redact(arguments),
+            "risk": risk,
+            "decision": decision,
+            "status": status,
+            "detail": detail,
+        }
+        line = json.dumps(entry, ensure_ascii=False)
+        with self._lock:
+            with self.path.open("a", encoding="utf-8") as fh:
+                fh.write(line + "\n")
+        return entry

superuser/authz.py

@@ -0,0 +1,155 @@
+"""Cisco Duo Agentic Identity authorization.
+
+Implements the client side of Duo's "Duo decides, the gateway enforces" model
+for per-tool-call authorization:
+
+- The agent authenticates as a registered non-human identity using the OAuth 2.1
+  client-credentials grant, requesting scopes (and, per RFC 8707, a resource
+  indicator naming the audience it intends to access).
+- Before each tool runs, the call is authorized either by an explicit Duo
+  decision endpoint (``authorization_url``) or, by default, by checking the
+  tool's required scope against the scopes Duo granted in the token.
+
+Only ``requests`` is needed (no extra SDK). When Duo is not configured the
+authorizer degrades gracefully: calls are allowed but flagged UNGOVERNED. In
+``enforce`` mode, authorization errors fail closed; in ``monitor`` they are
+logged and allowed.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass
+
+import requests
+
+from .config import DuoConfig
+
+logger = logging.getLogger("superuser.authz")
+
+
+@dataclass
+class AuthzDecision:
+    allowed: bool
+    governed: bool
+    reason: str
+
+    @classmethod
+    def ungoverned(cls) -> "AuthzDecision":
+        return cls(allowed=True, governed=False, reason="Duo not configured")
+
+    @classmethod
+    def allow(cls, reason: str = "authorized") -> "AuthzDecision":
+        return cls(allowed=True, governed=True, reason=reason)
+
+    @classmethod
+    def deny(cls, reason: str) -> "AuthzDecision":
+        return cls(allowed=False, governed=True, reason=reason)
+
+
+class DuoAuthorizer:
+    def __init__(self, config: DuoConfig) -> None:
+        self.config = config
+        self._token: str | None = None
+        self._granted_scopes: set[str] = set()
+        self._token_expiry: float = 0.0
+
+    def _fetch_token(self) -> str | None:
+        """Client-credentials grant; caches the token until shortly before expiry."""
+        now = time.time()
+        if self._token and now < self._token_expiry:
+            return self._token
+
+        data = {"grant_type": "client_credentials"}
+        if self.config.scopes:
+            data["scope"] = " ".join(self.config.scopes)
+        if self.config.resource:
+            data["resource"] = self.config.resource  # RFC 8707
+
+        resp = requests.post(
+            self.config.token_url,
+            data=data,
+            auth=(self.config.client_id, self.config.client_secret),
+            headers={"Accept": "application/json"},
+            timeout=15,
+        )
+        if resp.status_code >= 400:
+            raise RuntimeError(f"Duo token endpoint {resp.status_code}: {resp.text[:300]}")
+
+        body = resp.json()
+        self._token = body.get("access_token")
+        granted = body.get("scope", "")
+        self._granted_scopes = set(granted.split()) if granted else set(self.config.scopes)
+        self._token_expiry = now + int(body.get("expires_in", 300)) - 30
+        return self._token
+
+    def authorize(self, tool_name: str, arguments: dict, risk: str) -> AuthzDecision:
+        if not self.config.can_enforce:
+            return AuthzDecision.ungoverned()
+        try:
+            token = self._fetch_token()
+            if not token:
+                raise RuntimeError("no access token returned by Duo")
+
+            if self.config.authorization_url:
+                return self._authorize_via_endpoint(token, tool_name, arguments, risk)
+            return self._authorize_via_scopes(tool_name)
+        except Exception as exc:
+            logger.error("Duo authorization error for %s: %s", tool_name, exc)
+            if self.config.mode == "monitor":
+                return AuthzDecision(True, True, f"authorization error (monitor): {exc}")
+            return AuthzDecision.deny(f"authorization error: {exc}")
+
+    def _authorize_via_scopes(self, tool_name: str) -> AuthzDecision:
+        required = self.config.tool_scopes.get(tool_name)
+        if required is None:
+            # No scope mapping for this tool: allow but note it's unmapped.
+            return AuthzDecision.allow("no scope requirement mapped")
+        if required in self._granted_scopes:
+            return AuthzDecision.allow(f"scope '{required}' granted")
+        reason = f"missing required scope '{required}'"
+        if self.config.mode == "monitor":
+            logger.warning("Duo (monitor) would deny %s: %s", tool_name, reason)
+            return AuthzDecision(True, True, f"{reason} (monitor)")
+        return AuthzDecision.deny(reason)
+
+    def _authorize_via_endpoint(
+        self, token: str, tool_name: str, arguments: dict, risk: str
+    ) -> AuthzDecision:
+        resp = requests.post(
+            self.config.authorization_url,
+            headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
+            json={
+                "agent_id": self.config.agent_id,
+                "resource": self.config.resource,
+                "tool": tool_name,
+                "action": tool_name,
+                "risk": risk,
+                "arguments": arguments,
+            },
+            timeout=15,
+        )
+        if resp.status_code == 403:
+            return AuthzDecision.deny("Duo policy denied this tool call")
+        if resp.status_code >= 400:
+            raise RuntimeError(f"Duo decision endpoint {resp.status_code}: {resp.text[:300]}")
+
+        body = resp.json() if resp.text else {}
+        decision = str(body.get("decision", body.get("action", "allow"))).lower()
+        if decision in ("allow", "permit", "allowed"):
+            return AuthzDecision.allow(body.get("reason", "authorized by Duo"))
+        reason = body.get("reason", "denied by Duo policy")
+        if self.config.mode == "monitor":
+            return AuthzDecision(True, True, f"{reason} (monitor)")
+        return AuthzDecision.deny(reason)
+
+    @property
+    def status(self) -> dict:
+        return {
+            "enabled": self.config.enabled,
+            "mode": self.config.mode,
+            "enforcing": self.config.can_enforce,
+            "agent_id": self.config.agent_id,
+            "authorization": "endpoint" if self.config.authorization_url else "scopes",
+        }

superuser/billing.py

@@ -0,0 +1,91 @@
+"""Stripe usage-based (metered) billing.
+
+After a tool call is authorized and executed successfully, the agent reports a
+Stripe meter event so it can be sold per-action. This uses Stripe's v2 billing
+meter events API via the official ``stripe`` SDK.
+
+Billing is strictly best-effort: it must never block or fail a tool call. If the
+SDK is missing, no key is configured, or Stripe returns an error, the failure is
+logged and the tool result is returned unchanged (annotated ``billed: false``).
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from dataclasses import dataclass
+
+from .config import StripeConfig
+
+logger = logging.getLogger("superuser.billing")
+
+
+@dataclass
+class BillingResult:
+    billed: bool
+    value: int = 0
+    identifier: str | None = None
+    detail: str | None = None
+
+
+class StripeMeter:
+    def __init__(self, config: StripeConfig) -> None:
+        self.config = config
+        self._client = None
+        self._available = self._probe_sdk()
+        if config.enabled and not self._available:
+            logger.warning(
+                "Stripe SDK not installed; usage will not be metered. "
+                "Install with: pip install 'superuser[billing]'"
+            )
+
+    @staticmethod
+    def _probe_sdk() -> bool:
+        try:
+            import stripe  # noqa: F401
+        except Exception:
+            return False
+        return True
+
+    def _get_client(self):
+        if self._client is not None:
+            return self._client
+        if not (self._available and self.config.can_bill):
+            return None
+        import stripe
+
+        self._client = stripe.StripeClient(self.config.api_key)
+        return self._client
+
+    def record(self, tool_name: str) -> BillingResult:
+        if not self.config.enabled:
+            return BillingResult(billed=False, detail="billing disabled")
+        client = self._get_client()
+        if client is None:
+            return BillingResult(billed=False, detail="billing not configured")
+
+        value = self.config.value_for(tool_name)
+        identifier = f"{tool_name}:{uuid.uuid4()}"
+        try:
+            client.v2.billing.meter_events.create({
+                "event_name": self.config.event_name,
+                "identifier": identifier,
+                "payload": {
+                    "stripe_customer_id": self.config.customer_id,
+                    "value": str(value),
+                    "tool": tool_name,
+                },
+            })
+            return BillingResult(billed=True, value=value, identifier=identifier)
+        except Exception as exc:  # billing must never break the tool call
+            logger.error("Stripe meter event failed for %s: %s", tool_name, exc)
+            return BillingResult(billed=False, value=value, detail=str(exc))
+
+    @property
+    def status(self) -> dict:
+        return {
+            "sdk_installed": self._available,
+            "enabled": self.config.enabled,
+            "configured": bool(self.config.can_bill),
+            "event_name": self.config.event_name,
+        }