proxy-aiops 0.1.0__py3-none-any.whl

mcp_server/tools/undo.py

@@ -0,0 +1,121 @@
+"""Undo executor — list recorded inverse descriptors and APPLY them.
+
+Every governed write records a replayable inverse descriptor (tool + params) to
+``undo.db``. This module closes the loop: ``undo_apply`` looks up a recorded
+descriptor and dispatches it to the named governed tool, so the inverse runs on
+the SAME governance path as any other call (audited, budget-checked, and — if
+the inverse itself is destructive — re-gated by its own risk tier / approver
+requirement). ``undo_apply`` is itself governed; the real risk is enforced by
+the inner tool it calls.
+
+Note: recorded ``undo_params`` are the redacted safe-params captured at record
+time, so an inverse that would need a secret value cannot be replayed here — by
+design, inverses in this line key off ids/names, not credentials.
+"""
+
+import json
+from typing import Any, Optional
+
+from mcp_server._shared import mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.governance.undo import get_undo_store
+
+
+def _resolve_tool(name: str) -> Any:
+    """Return the governed callable registered under ``name`` (or None)."""
+    tool = mcp._tool_manager._tools.get(name)
+    return getattr(tool, "fn", None) if tool else None
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
+    """[READ] List recorded, not-yet-applied undo tokens (most recent first).
+
+    Each entry names the original tool, the inverse tool that ``undo_apply``
+    would run, and a human note. Use the ``undoId`` with ``undo_apply``.
+
+    Args:
+        limit: Max rows to return (default 50).
+        target: Unused (undo state is host-local); accepted for CLI uniformity.
+    """
+    rows = get_undo_store().list(status="recorded", limit=max(1, min(limit, 500)))
+    return {
+        "count": len(rows),
+        "undos": [
+            {
+                "undoId": r["undo_id"],
+                "ts": r["ts"],
+                "originalTool": r["tool"],
+                "inverseTool": r["undo_tool"],
+                "note": r.get("note", ""),
+            }
+            for r in rows
+        ],
+    }
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
+
+    The inverse runs through its own governed tool, so its real risk tier and
+    any approver requirement are enforced there. Pass dry_run=True to preview
+    the inverse call without executing it. A token can only be applied once.
+
+    Args:
+        undo_id: The undoId from undo_list (or an ``_undo_id`` in a write result).
+        dry_run: If True, preview the inverse tool + params without running it.
+        target: Passed through to the inverse tool when it accepts a target.
+    """
+    store = get_undo_store()
+    rec = store.get(undo_id)
+    if not rec:
+        raise ValueError(f"Unknown undo id '{undo_id}'. Run undo_list to see available tokens.")
+    if rec["status"] != "recorded":
+        raise ValueError(
+            f"Undo '{undo_id}' is already '{rec['status']}' — a token can only be applied once."
+        )
+
+    inverse_tool = rec["undo_tool"]
+    try:
+        params = json.loads(rec["undo_params"]) if rec["undo_params"] else {}
+    except (ValueError, TypeError):
+        params = {}
+    if not isinstance(params, dict):
+        params = {}
+
+    fn = _resolve_tool(inverse_tool)
+    if fn is None:
+        raise ValueError(
+            f"Inverse tool '{inverse_tool}' is not registered on this server; cannot apply."
+        )
+
+    if dry_run:
+        return {
+            "dryRun": True,
+            "undoId": undo_id,
+            "wouldApply": {"tool": inverse_tool, "params": params},
+        }
+
+    call_params = dict(params)
+    if target is not None and "target" not in call_params:
+        call_params["target"] = target
+    result = fn(**call_params)
+
+    # Only mark applied when the inverse did not itself return an error dict.
+    if not (isinstance(result, dict) and result.get("error")):
+        store.mark(undo_id, "applied")
+        applied = True
+    else:
+        applied = False
+
+    return {
+        "undoId": undo_id,
+        "applied": applied,
+        "inverseTool": inverse_tool,
+        "result": result,
+    }

mcp_server/tools/writes.py

@@ -0,0 +1,265 @@
+"""Governed proxy-write MCP tools (the only state-changing tools).
+
+Every tool is wrapped with the governance harness (audit + graduated approval
+tier) and takes a ``dry_run`` preview. Reversible writes pass an ``undo=``
+callback that turns the fetched before-state into an inverse descriptor the
+harness records; the undo params match the target tool's own signature, so the
+descriptor is replayable as-is.
+
+Risk tiers: delete_config_path / load_config = high (delete / full replace);
+set_config_value / set_server_state / set_server_weight = medium.
+
+Platform dispatch is the support matrix's job: a write against the wrong
+platform raises its teaching error (traefik writes → edit the provider;
+haproxy config writes → transactions out of scope) before anything mutates.
+"""
+
+from typing import Any, Optional
+
+from mcp_server._shared import _get_connection, mcp, tool_errors
+from proxy_aiops.governance import governed_tool
+from proxy_aiops.ops import writes as ops
+
+# ── undo descriptors (built from the fetched before-state) ──────────────────
+
+
+def _set_config_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of set_config_value: restore the prior subtree (or delete a
+    path that did not exist before)."""
+    if not isinstance(result, dict):
+        return None
+    prior = result.get("priorState") or {}
+    if prior.get("existed"):
+        return {
+            "tool": "set_config_value",
+            "params": {"path": params.get("path"), "value": prior.get("value")},
+            "skill": "proxy-aiops",
+            "note": "Inverse of set_config_value: restore the prior config subtree.",
+        }
+    return {
+        "tool": "delete_config_path",
+        "params": {"path": params.get("path")},
+        "skill": "proxy-aiops",
+        "note": "Inverse of set_config_value: the path did not exist before — delete it.",
+    }
+
+
+def _delete_config_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of delete_config_path: re-create the deleted subtree."""
+    if not isinstance(result, dict):
+        return None
+    prior = result.get("priorState") or {}
+    if not prior.get("existed"):
+        return None
+    return {
+        "tool": "set_config_value",
+        "params": {"path": params.get("path"), "value": prior.get("value")},
+        "skill": "proxy-aiops",
+        "note": "Inverse of delete_config_path: re-create the deleted subtree.",
+    }
+
+
+def _load_config_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of load_config: re-load the snapshotted prior config."""
+    if not isinstance(result, dict):
+        return None
+    prior = (result.get("priorState") or {}).get("config")
+    if not isinstance(prior, dict) or not prior:
+        return None
+    return {
+        "tool": "load_config",
+        "params": {"config": prior},
+        "skill": "proxy-aiops",
+        "note": "Inverse of load_config: restore the snapshotted prior config.",
+    }
+
+
+def _server_state_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of set_server_state: restore the prior admin state."""
+    if not isinstance(result, dict):
+        return None
+    prior = (result.get("priorState") or {}).get("adminState")
+    if prior not in ops.SERVER_STATES:
+        return None
+    return {
+        "tool": "set_server_state",
+        "params": {
+            "backend": params.get("backend"),
+            "server": params.get("server"),
+            "state": prior,
+        },
+        "skill": "proxy-aiops",
+        "note": "Inverse of set_server_state: restore the prior admin state.",
+    }
+
+
+def _server_weight_undo(params: dict[str, Any], result: Any) -> Optional[dict]:
+    """Inverse of set_server_weight: restore the prior weight."""
+    if not isinstance(result, dict):
+        return None
+    prior = (result.get("priorState") or {}).get("weight")
+    if prior is None:
+        return None
+    return {
+        "tool": "set_server_weight",
+        "params": {
+            "backend": params.get("backend"),
+            "server": params.get("server"),
+            "weight": prior,
+        },
+        "skill": "proxy-aiops",
+        "note": "Inverse of set_server_weight: restore the prior weight.",
+    }
+
+
+# ── caddy config writes ──────────────────────────────────────────────────────
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_set_config_undo)
+@tool_errors("dict")
+def set_config_value(
+    path: str,
+    value: Any,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Set a caddy config subtree (e.g. a route's
+    upstreams); reversible — the prior subtree is fetched first and the undo
+    restores it.
+
+    Caddy applies the change immediately. On traefik/haproxy this raises the
+    support matrix's teaching error. Pass dry_run=True to preview.
+
+    Args:
+        path: Slash-separated config path (from search_config / list_routes,
+            e.g. apps/http/servers/srv0/routes/0/handle/0/upstreams).
+        value: The JSON value to write at that path.
+        dry_run: If True, preview without changing.
+        target: Proxy target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldSet": {"path": path, "value": value}}
+    return ops.set_config_value(conn, path, value)
+
+
+@mcp.tool()
+@governed_tool(risk_level="high", undo=_delete_config_undo)
+@tool_errors("dict")
+def delete_config_path(
+    path: str,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=high] Delete a caddy config subtree; reversible — the
+    subtree is captured first and the undo re-creates it.
+
+    Requires an approver (PROXY_AUDIT_APPROVED_BY) under the
+    graduated-autonomy policy. Pass dry_run=True to preview.
+
+    Args:
+        path: Slash-separated config path to delete.
+        dry_run: If True, preview without deleting.
+        target: Proxy target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldDelete": {"path": path}}
+    return ops.delete_config_path(conn, path)
+
+
+@mcp.tool()
+@governed_tool(risk_level="high", undo=_load_config_undo)
+@tool_errors("dict")
+def load_config(
+    config: dict,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=high] Replace caddy's FULL running config; reversible —
+    the prior config is snapshotted first and the undo re-loads it.
+
+    Requires an approver (PROXY_AUDIT_APPROVED_BY) under the
+    graduated-autonomy policy. Pass dry_run=True to preview.
+
+    Args:
+        config: The full config tree to load (a JSON object).
+        dry_run: If True, preview without loading.
+        target: Proxy target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {"dryRun": True, "wouldLoad": {"topLevelKeys": sorted(config or {})}}
+    return ops.load_config(conn, config)
+
+
+# ── haproxy runtime-server writes ────────────────────────────────────────────
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_server_state_undo)
+@tool_errors("dict")
+def set_server_state(
+    backend: str,
+    server: str,
+    state: str,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Set an haproxy server's admin state (ready / drain
+    / maint); reversible — the prior admin state is fetched first and the undo
+    restores it.
+
+    drain finishes in-flight sessions but takes no new ones; maint removes the
+    server immediately; ready returns it to rotation. On traefik/caddy this
+    raises the support matrix's teaching error. Pass dry_run=True to preview.
+
+    Args:
+        backend: Backend name (from list_services).
+        server: Server name inside the backend (from list_upstreams).
+        state: One of ready, drain, maint.
+        dry_run: If True, preview without changing.
+        target: Proxy target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {
+            "dryRun": True,
+            "wouldSetState": {"backend": backend, "server": server, "state": state},
+        }
+    return ops.set_server_state(conn, backend, server, state)
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium", undo=_server_weight_undo)
+@tool_errors("dict")
+def set_server_weight(
+    backend: str,
+    server: str,
+    weight: int,
+    dry_run: bool = False,
+    target: Optional[str] = None,
+) -> dict:
+    """[WRITE][risk=medium] Set an haproxy server's load-balancing weight
+    (0-256); reversible — the prior weight is fetched first and the undo
+    restores it.
+
+    Weight 0 stops new traffic to the server without a state change. On
+    traefik/caddy this raises the support matrix's teaching error. Pass
+    dry_run=True to preview.
+
+    Args:
+        backend: Backend name (from list_services).
+        server: Server name inside the backend (from list_upstreams).
+        weight: New weight, 0-256.
+        dry_run: If True, preview without changing.
+        target: Proxy target name from config; omit for the default.
+    """
+    conn = _get_connection(target)
+    if dry_run:
+        return {
+            "dryRun": True,
+            "wouldSetWeight": {"backend": backend, "server": server, "weight": weight},
+        }
+    return ops.set_server_weight(conn, backend, server, weight)

proxy_aiops/__init__.py

@@ -0,0 +1,14 @@
+"""proxy-aiops — governed Traefik + Caddy + HAProxy proxy operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, output sanitize) is
+bundled under ``proxy_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("proxy-aiops")
+except PackageNotFoundError:  # running from an uninstalled source tree
+    __version__ = "0.0.0+unknown"

proxy_aiops/cli/__init__.py

@@ -0,0 +1,5 @@
+"""proxy-aiops CLI package — exposes the Typer app."""
+
+from proxy_aiops.cli._root import app
+
+__all__ = ["app"]

proxy_aiops/cli/_common.py

@@ -0,0 +1,78 @@
+"""Shared helpers for proxy-aiops CLI sub-modules."""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+
+console = Console()
+
+# ─── Shared Option types ───────────────────────────────────────────────────
+
+TargetOption = Annotated[
+    str | None, typer.Option("--target", "-t", help="Target name from config")
+]
+DryRunOption = Annotated[
+    bool, typer.Option("--dry-run", help="Print the API call without executing")
+]
+
+
+def _cli_error_types() -> tuple[type[BaseException], ...]:
+    """Exceptions translated to a one-line teaching error instead of a traceback."""
+    from proxy_aiops.connection import ProxyApiError
+
+    return (ProxyApiError, KeyError, OSError, ValueError)
+
+
+def cli_errors(fn: Callable) -> Callable:
+    """Translate known exceptions into one red line + exit code 1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except (typer.Exit, typer.Abort):
+            raise
+        except _cli_error_types() as e:
+            message = str(e)
+            if isinstance(e, KeyError):
+                message = f"Missing required key or environment variable: {message}"
+            console.print(f"[red]Error: {message}[/]")
+            raise typer.Exit(1) from e
+
+    return wrapper
+
+
+def get_connection(target: str | None, config_path: Path | None = None) -> tuple[Any, Any]:
+    """Return a (conn, config) tuple for the given target."""
+    from proxy_aiops.config import load_config
+    from proxy_aiops.connection import ConnectionManager
+
+    cfg = load_config(config_path)
+    mgr = ConnectionManager(cfg)
+    return mgr.connect(target), cfg
+
+
+def dry_run_print(*, operation: str, api_call: str, parameters: dict | None = None) -> None:
+    """Print a dry-run preview of the API call that would be made."""
+    console.print("\n[bold magenta][DRY-RUN] No changes will be made.[/]")
+    console.print(f"[magenta]  Operation: {operation}[/]")
+    console.print(f"[magenta]  API Call:  {api_call}[/]")
+    for k, v in (parameters or {}).items():
+        console.print(f"[magenta]  Param:     {k} = {v}[/]")
+    console.print("[magenta]  Run without --dry-run to execute.[/]\n")
+
+
+def double_confirm(action: str, resource: str) -> None:
+    """Require two confirmations for a destructive operation."""
+    console.print(f"[bold yellow]⚠️  About to: {action} '{resource}'[/]")
+    typer.confirm(f"Confirm 1/2: {action} '{resource}'?", abort=True)
+    typer.confirm(
+        f"Confirm 2/2: really {action} '{resource}'? This may be irreversible.",
+        abort=True,
+    )

proxy_aiops/cli/_root.py

@@ -0,0 +1,68 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from proxy_aiops.cli._common import cli_errors
+from proxy_aiops.cli.analyze import analyze_app
+from proxy_aiops.cli.certs import certs_cmd
+from proxy_aiops.cli.configcmd import config_app
+from proxy_aiops.cli.doctor import doctor_cmd
+from proxy_aiops.cli.init import init_cmd
+from proxy_aiops.cli.overview import overview_cmd
+from proxy_aiops.cli.routes import routes_app
+from proxy_aiops.cli.secret import secret_app
+from proxy_aiops.cli.server import server_app
+from proxy_aiops.cli.services import services_app
+from proxy_aiops.cli.undo import undo_app
+
+app = typer.Typer(
+    name="proxy-aiops",
+    help="Governed AI-ops for Traefik + Caddy + HAProxy: routes, services, "
+    "upstream health, certs, error-rate RCA, and governed writes (caddy "
+    "config, haproxy server state/weight).",
+    no_args_is_help=True,
+)
+
+app.add_typer(routes_app, name="routes")
+app.add_typer(services_app, name="services")
+app.add_typer(analyze_app, name="analyze")
+app.add_typer(config_app, name="config")
+app.add_typer(server_app, name="server")
+app.add_typer(secret_app, name="secret")
+app.add_typer(undo_app, name="undo")
+app.command("init")(init_cmd)
+app.command("overview")(overview_cmd)
+app.command("certs")(certs_cmd)
+app.command("doctor")(doctor_cmd)
+
+
+@app.command("mcp")
+@cli_errors
+def mcp_cmd() -> None:
+    """Start the MCP server (stdio transport).
+
+    Single-command entry point for MCP clients (does not go through uvx/PyPI
+    resolution at launch):
+        proxy-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: proxy-aiops requires Python >= 3.11 "
+            f"(got {sys.version_info.major}.{sys.version_info.minor}).\n"
+            f"Fix: uv python install 3.12 && "
+            f"uv tool install --python 3.12 --force proxy-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

proxy_aiops/cli/analyze.py

@@ -0,0 +1,81 @@
+"""``proxy-aiops analyze`` — the flagship RCA analyses from the CLI."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from proxy_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+analyze_app = typer.Typer(
+    name="analyze",
+    help="Flagship analyses: backend health RCA, error-rate RCA, route conflicts.",
+    no_args_is_help=True,
+)
+
+
+@analyze_app.command("health")
+@cli_errors
+def analyze_health(
+    service: Annotated[
+        str | None, typer.Option("--service", "-s", help="Filter by service/backend")
+    ] = None,
+    target: TargetOption = None,
+) -> None:
+    """Backend/upstream health RCA: down servers grouped per service, cause + action."""
+    from proxy_aiops.ops import analysis as analysis_ops
+    from proxy_aiops.ops import services as svc_ops
+
+    conn, _ = get_connection(target)
+    pulled = svc_ops.list_upstreams(conn, service)
+    if "error" in pulled:
+        console.print_json(json.dumps(pulled))
+        raise typer.Exit(1)
+    console.print_json(json.dumps(analysis_ops.backend_health_rca(pulled["upstreams"])))
+
+
+@analyze_app.command("errors")
+@cli_errors
+def analyze_errors(
+    error_rate_pct: Annotated[
+        float, typer.Option("--rate", help="5xx %% at/above which a service is flagged")
+    ] = 5.0,
+    min_requests: Annotated[
+        float, typer.Option("--min-requests", help="Minimum requests to be flagged")
+    ] = 30.0,
+    target: TargetOption = None,
+) -> None:
+    """5xx / error-rate RCA vs the fleet baseline, cause + action per service."""
+    from proxy_aiops.ops import analysis as analysis_ops
+    from proxy_aiops.ops import traffic as traffic_ops
+
+    conn, _ = get_connection(target)
+    pulled = traffic_ops.error_counters(conn)
+    if "error" in pulled:
+        console.print_json(json.dumps(pulled))
+        raise typer.Exit(1)
+    console.print_json(json.dumps(analysis_ops.error_rate_rca(
+        pulled["services"], error_rate_pct=error_rate_pct, min_requests=min_requests
+    )))
+
+
+@analyze_app.command("conflicts")
+@cli_errors
+def analyze_conflicts(target: TargetOption = None) -> None:
+    """Route conflict & shadow analysis: shadowed / dead routes, redirect loops."""
+    from proxy_aiops.ops import analysis as analysis_ops
+    from proxy_aiops.ops import routes as route_ops
+    from proxy_aiops.ops import services as svc_ops
+
+    conn, _ = get_connection(target)
+    routes = route_ops.list_routes(conn)
+    if "error" in routes:
+        console.print_json(json.dumps(routes))
+        raise typer.Exit(1)
+    services = svc_ops.list_services(conn)
+    svc_rows = services.get("services") if "error" not in services else None
+    console.print_json(json.dumps(
+        analysis_ops.route_conflict_analysis(routes["routes"], svc_rows)
+    ))

proxy_aiops/cli/certs.py

@@ -0,0 +1,43 @@
+"""``proxy-aiops certs`` — TLS certificate inventory + expiry sweep."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from proxy_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+
+@cli_errors
+def certs_cmd(
+    sweep: Annotated[
+        bool,
+        typer.Option("--sweep/--no-sweep", help="Probe expiry and bucket by days-to-expiry"),
+    ] = True,
+    warn_days: Annotated[
+        float, typer.Option("--warn-days", help="Warning threshold (days)")
+    ] = 30.0,
+    critical_days: Annotated[
+        float, typer.Option("--critical-days", help="Critical threshold (days)")
+    ] = 7.0,
+    port: Annotated[int, typer.Option("--port", help="TLS port to probe")] = 443,
+    target: TargetOption = None,
+) -> None:
+    """TLS domain inventory; --sweep live-probes each cert's expiry."""
+    from proxy_aiops.ops import analysis as analysis_ops
+    from proxy_aiops.ops import certs as ops
+
+    conn, _ = get_connection(target)
+    inventory = ops.list_certificates(conn, probe=sweep, port=port)
+    if not sweep or "unsupported" in inventory or "error" in inventory:
+        console.print_json(json.dumps(inventory))
+        return
+    result = analysis_ops.cert_expiry_sweep(
+        inventory.get("certificates", []),
+        warn_days=warn_days,
+        critical_days=critical_days,
+        platform=conn.target.platform,
+    )
+    console.print_json(json.dumps(result))