ceph-aiops 0.1.0__py3-none-any.whl

ceph_aiops/__init__.py

@@ -0,0 +1,9 @@
+"""ceph-aiops — governed Ceph SCALE operations for AI agents.
+
+Standalone and self-contained: the governance harness (audit, token budget,
+undo-token recording, graduated risk tiers, prompt-injection sanitize) is
+bundled under ``ceph_aiops.governance`` — this package has no external
+skill-family dependency. Preview: not yet full-coverage.
+"""
+
+__version__ = "0.1.0"

ceph_aiops/cli/__init__.py

@@ -0,0 +1,9 @@
+"""CLI package for ceph-aiops.
+
+Re-exports ``app`` so the pyproject entry point
+``ceph-aiops = "ceph_aiops.cli:app"`` works unchanged.
+"""
+
+from ceph_aiops.cli._root import app
+
+__all__ = ["app"]

ceph_aiops/cli/_common.py

@@ -0,0 +1,78 @@
+"""Shared helpers for ceph-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 ceph_aiops.connection import CephApiError
+
+    return (CephApiError, 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):
+    """Return a (conn, config) tuple for the given target."""
+    from ceph_aiops.config import load_config
+    from ceph_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,
+    )

ceph_aiops/cli/_root.py

@@ -0,0 +1,57 @@
+"""Top-level Typer app: assembles sub-apps and top-level commands."""
+
+from __future__ import annotations
+
+import typer
+
+from ceph_aiops.cli._common import cli_errors
+from ceph_aiops.cli.doctor import doctor_cmd
+from ceph_aiops.cli.health import health_app
+from ceph_aiops.cli.init import init_cmd
+from ceph_aiops.cli.osd import osd_app
+from ceph_aiops.cli.overview import overview_cmd
+from ceph_aiops.cli.secret import secret_app
+
+app = typer.Typer(
+    name="ceph-aiops",
+    help="Governed AI-ops for Ceph (mgr Dashboard REST): health RCA, OSD/PG/pool, "
+    "RBD/CephFS/RGW, recovery, capacity.",
+    no_args_is_help=True,
+)
+
+app.add_typer(health_app, name="health")
+app.add_typer(osd_app, name="osd")
+app.add_typer(secret_app, name="secret")
+app.command("init")(init_cmd)
+app.command("overview")(overview_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):
+        ceph-aiops mcp
+    """
+    import sys
+
+    if sys.version_info < (3, 11):
+        typer.echo(
+            f"ERROR: ceph-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 ceph-aiops",
+            err=True,
+        )
+        raise typer.Exit(2)
+
+    from mcp_server.server import main as _mcp_main
+
+    _mcp_main()
+
+
+if __name__ == "__main__":
+    app()

ceph_aiops/cli/doctor.py

@@ -0,0 +1,21 @@
+"""Doctor top-level command: environment and connectivity check."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from ceph_aiops.cli._common import cli_errors
+
+
+@cli_errors
+def doctor_cmd(
+    skip_auth: Annotated[
+        bool, typer.Option("--skip-auth", help="Skip connectivity check (faster)")
+    ] = False,
+) -> None:
+    """Check environment, config, secrets, and connectivity."""
+    from ceph_aiops.doctor import run_doctor
+
+    raise typer.Exit(run_doctor(skip_auth=skip_auth))

ceph_aiops/cli/health.py

@@ -0,0 +1,35 @@
+"""``ceph-aiops health`` — cluster health + status reads."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from ceph_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+health_app = typer.Typer(
+    name="health",
+    help="Cluster health (RCA) and status.",
+    no_args_is_help=True,
+)
+
+
+@health_app.command("detail")
+@cli_errors
+def health_detail(target: TargetOption = None) -> None:
+    """HEALTH status with a cause + suggested action per active check."""
+    from ceph_aiops.ops import health as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.cluster_health(conn)))
+
+
+@health_app.command("status")
+@cli_errors
+def health_status(target: TargetOption = None) -> None:
+    """Compact ceph -s summary (mons, OSDs, PGs, usage)."""
+    from ceph_aiops.ops import health as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.cluster_status(conn)))

ceph_aiops/cli/init.py

@@ -0,0 +1,103 @@
+"""``ceph-aiops init`` — a friendly, interactive onboarding wizard.
+
+Walks a new user through connecting their first Ceph SCALE target: collects
+the non-secret connection details into ``config.yaml`` and the API key into the
+*encrypted* store (never plaintext on disk). Designed to be run on a terminal;
+everything it needs is prompted with sensible defaults.
+"""
+
+from __future__ import annotations
+
+import getpass
+
+import typer
+import yaml
+
+from ceph_aiops.cli._common import cli_errors, console
+from ceph_aiops.config import CONFIG_DIR, CONFIG_FILE, DEFAULT_MGR_PORT, DEFAULT_USERNAME
+from ceph_aiops.secretstore import SecretStore, resolve_master_password
+
+
+def _load_existing_targets() -> list[dict]:
+    if not CONFIG_FILE.exists():
+        return []
+    raw = yaml.safe_load(CONFIG_FILE.read_text("utf-8")) or {}
+    return list(raw.get("targets", []))
+
+
+def _write_targets(targets: list[dict]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        CONFIG_DIR.chmod(0o700)
+    except OSError:
+        pass
+    CONFIG_FILE.write_text(yaml.safe_dump({"targets": targets}, sort_keys=False), "utf-8")
+
+
+@cli_errors
+def init_cmd() -> None:
+    """Interactively set up your first Ceph connection."""
+    console.print("[bold cyan]Ceph AIops — setup wizard[/]")
+    console.print(
+        "This collects ceph-mgr Dashboard connection details (saved to "
+        "config.yaml) and your Dashboard password (saved [bold]encrypted[/] to "
+        "secrets.enc).\n"
+    )
+
+    console.print("[bold]Step 1 — master password[/]")
+    console.print(
+        "[dim]Encrypts secrets.enc. You'll set it via the "
+        "CEPH_AIOPS_MASTER_PASSWORD env var for non-interactive/MCP use.[/]"
+    )
+    password = resolve_master_password(confirm_if_new=True)
+    store = SecretStore.unlock(password)
+
+    targets = _load_existing_targets()
+    existing_names = {t.get("name") for t in targets}
+
+    while True:
+        console.print("\n[bold]Step 2 — add a Ceph cluster[/]")
+        name = typer.prompt("Target name (e.g. lab1)").strip()
+        if name in existing_names:
+            if not typer.confirm(f"'{name}' already exists — overwrite?", default=False):
+                continue
+            targets = [t for t in targets if t.get("name") != name]
+
+        host = typer.prompt("Host (IP or FQDN of the active ceph-mgr)").strip()
+        port = typer.prompt("Dashboard HTTPS port", default=DEFAULT_MGR_PORT, type=int)
+        username = typer.prompt("Dashboard username", default=DEFAULT_USERNAME).strip()
+        verify_ssl = typer.confirm(
+            "Verify TLS certificate? (No for self-signed lab certs)", default=False
+        )
+
+        console.print(
+            "[dim]Enter the ceph-mgr Dashboard password for this account "
+            "(input hidden). The mgr 'dashboard' module must be enabled.[/]"
+        )
+        secret = getpass.getpass(f"Password for '{username}@{name}' (hidden): ")
+        store = store.set(name, secret)
+
+        entry = {
+            "name": name,
+            "host": host,
+            "port": port,
+            "username": username,
+            "verify_ssl": verify_ssl,
+        }
+        targets.append(entry)
+        existing_names.add(name)
+        _write_targets(targets)
+        console.print(f"[green]✓ Saved target '{name}' (password stored encrypted).[/]")
+
+        if not typer.confirm("\nAdd another target?", default=False):
+            break
+
+    console.print(f"\n[green]✓ Setup complete.[/] Config: {CONFIG_FILE}")
+    console.print(
+        "[dim]Tip: export CEPH_AIOPS_MASTER_PASSWORD=... in your shell profile "
+        "so the MCP server and CLI can unlock secrets non-interactively.[/]"
+    )
+    if typer.confirm("Run a connectivity check now (ceph-aiops doctor)?", default=True):
+        from ceph_aiops.doctor import run_doctor
+
+        raise typer.Exit(run_doctor())

ceph_aiops/cli/osd.py

@@ -0,0 +1,95 @@
+"""``ceph-aiops osd`` — OSD reads + guarded lifecycle writes."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from ceph_aiops.cli._common import (
+    DryRunOption,
+    TargetOption,
+    cli_errors,
+    console,
+    double_confirm,
+    dry_run_print,
+    get_connection,
+)
+
+osd_app = typer.Typer(
+    name="osd",
+    help="OSDs: tree/df/perf, reweight, mark in/out, purge.",
+    no_args_is_help=True,
+)
+
+IdArg = Annotated[int, typer.Argument(help="Numeric OSD id (from 'osd tree')")]
+
+
+@osd_app.command("tree")
+@cli_errors
+def osd_tree(target: TargetOption = None) -> None:
+    """List OSDs (up/in, weight, host, device class)."""
+    from ceph_aiops.ops import osd as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.osd_tree(conn)))
+
+
+@osd_app.command("df")
+@cli_errors
+def osd_df(target: TargetOption = None) -> None:
+    """Per-OSD utilisation (most-full first)."""
+    from ceph_aiops.ops import osd as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.osd_df(conn)))
+
+
+@osd_app.command("reweight")
+@cli_errors
+def osd_reweight(
+    osd_id: IdArg,
+    weight: Annotated[float, typer.Argument(help="New reweight 0.0–1.0 (0.0 = drain)")],
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Set an OSD's reweight (0.0 drains it)."""
+    from ceph_aiops.ops import osd as ops
+
+    if dry_run:
+        dry_run_print(operation="osd_reweight",
+                      api_call=f"POST /api/osd/{osd_id}/reweight",
+                      parameters={"weight": weight})
+        return
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.osd_reweight(conn, osd_id, weight)))
+
+
+@osd_app.command("out")
+@cli_errors
+def osd_out(osd_id: IdArg, target: TargetOption = None, dry_run: DryRunOption = False) -> None:
+    """Mark an OSD out — drains its data (dry-run + double confirm)."""
+    from ceph_aiops.ops import osd as ops
+
+    if dry_run:
+        dry_run_print(operation="mark_osd_out", api_call=f"POST /api/osd/{osd_id}/mark",
+                      parameters={"action": "out"})
+        return
+    double_confirm("mark out OSD", str(osd_id))
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.mark_osd(conn, osd_id, "out")))
+
+
+@osd_app.command("purge")
+@cli_errors
+def osd_purge(osd_id: IdArg, target: TargetOption = None, dry_run: DryRunOption = False) -> None:
+    """Purge an OSD — irreversible (dry-run + double confirm)."""
+    from ceph_aiops.ops import osd as ops
+
+    if dry_run:
+        dry_run_print(operation="osd_purge", api_call=f"DELETE /api/osd/{osd_id}")
+        return
+    double_confirm("purge OSD", str(osd_id))
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.osd_purge(conn, osd_id)))

ceph_aiops/cli/overview.py

@@ -0,0 +1,16 @@
+"""``ceph-aiops overview`` — one-shot fleet health."""
+
+from __future__ import annotations
+
+import json
+
+from ceph_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+
+@cli_errors
+def overview_cmd(target: TargetOption = None) -> None:
+    """One-shot cluster summary: HEALTH status + active checks + OSD up/in counts."""
+    from ceph_aiops.ops import overview as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.fleet_overview(conn)))

ceph_aiops/cli/secret.py

@@ -0,0 +1,103 @@
+"""``ceph-aiops secret`` — manage the encrypted credential store.
+
+Secrets (Ceph API keys) are stored in ``~/.ceph-aiops/secrets.enc``
+(Fernet, key derived from a master password via scrypt). Nothing here ever
+prints a secret value.
+"""
+
+from __future__ import annotations
+
+import getpass
+from typing import Annotated
+
+import typer
+
+from ceph_aiops.cli._common import cli_errors, console
+from ceph_aiops.config import SECRET_ENV_PREFIX, SECRET_ENV_SUFFIX
+from ceph_aiops.secretstore import (
+    SECRETS_FILE,
+    SecretStore,
+    check_permissions,
+    migrate_legacy_env,
+    resolve_master_password,
+)
+
+secret_app = typer.Typer(
+    name="secret",
+    help="Manage the encrypted credential store (secrets.enc).",
+    no_args_is_help=True,
+)
+
+NameArg = Annotated[str, typer.Argument(help="Target name the API key belongs to")]
+
+
+@secret_app.command("set")
+@cli_errors
+def secret_set(
+    name: NameArg,
+    value: Annotated[
+        str | None,
+        typer.Option("--value", help="API key value (omit to be prompted, hidden)"),
+    ] = None,
+) -> None:
+    """Store (or replace) the API key for a target — value is read hidden."""
+    password = resolve_master_password(confirm_if_new=True)
+    if value is None:
+        value = getpass.getpass(f"API key for '{name}' (hidden): ")
+    store = SecretStore.unlock(password)
+    store.set(name, value)
+    console.print(f"[green]✓ Stored encrypted API key for '{name}' in {SECRETS_FILE}[/]")
+
+
+@secret_app.command("list")
+@cli_errors
+def secret_list() -> None:
+    """List target names that have a stored API key (values never shown)."""
+    store = SecretStore.unlock()
+    names = store.names()
+    if not names:
+        console.print("[yellow]No secrets stored yet. Add one: ceph-aiops secret set <name>[/]")
+        return
+    console.print("[bold]Stored secrets:[/]")
+    for n in names:
+        console.print(f"  • {n}")
+    warning = check_permissions()
+    if warning:
+        console.print(f"[yellow]! {warning}[/]")
+
+
+@secret_app.command("rm")
+@cli_errors
+def secret_rm(name: NameArg) -> None:
+    """Delete a stored API key."""
+    store = SecretStore.unlock()
+    store.delete(name)
+    console.print(f"[green]✓ Deleted API key for '{name}'[/]")
+
+
+@secret_app.command("migrate")
+@cli_errors
+def secret_migrate() -> None:
+    """Import API keys from a legacy plaintext .env into the encrypted store."""
+    password = resolve_master_password(confirm_if_new=True)
+    imported = migrate_legacy_env(SECRET_ENV_PREFIX, SECRET_ENV_SUFFIX, password)
+    if not imported:
+        console.print("[yellow]Nothing to migrate (no legacy .env secrets found).[/]")
+        return
+    console.print(f"[green]✓ Imported {len(imported)} secret(s): {', '.join(imported)}[/]")
+    console.print("[dim]The old .env was renamed to .env.migrated — delete it once verified.[/]")
+
+
+@secret_app.command("rotate-password")
+@cli_errors
+def secret_rotate_password() -> None:
+    """Re-encrypt the whole store under a new master password."""
+    console.print("[bold]Unlock with the current master password:[/]")
+    store = SecretStore.unlock()
+    new_pw = getpass.getpass("New master password: ")
+    confirm = getpass.getpass("Confirm new master password: ")
+    if new_pw != confirm:
+        console.print("[red]Passwords did not match. Aborted.[/]")
+        raise typer.Exit(1)
+    store.with_password(new_pw)
+    console.print("[green]✓ Master password rotated. Update CEPH_AIOPS_MASTER_PASSWORD.[/]")

ceph_aiops/config.py

@@ -0,0 +1,139 @@
+"""Configuration management for Ceph AIops.
+
+Loads Ceph mgr (Dashboard REST) connection targets from a YAML config file. The
+secret (the Ceph Dashboard account **password**) is NEVER stored in the config
+file and never on disk in plaintext: it lives in the encrypted store
+``~/.ceph-aiops/secrets.enc`` (see :mod:`ceph_aiops.secretstore`). For backward
+compatibility a legacy plaintext env var (``CEPH_<TARGET>_PASSWORD``) is still
+honoured as a fallback, with a warning nudging migration to the encrypted store.
+
+A "target" is one Ceph cluster reached through its **ceph-mgr Dashboard REST
+API** (default HTTPS port ``8443``). Auth is username + password exchanged for a
+short-lived JWT at ``POST /api/auth`` (handled in
+:mod:`ceph_aiops.connection`). ``username`` lives in the config file (it is not a
+secret); the password lives encrypted.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from ceph_aiops.secretstore import SecretStoreError, get_secret, has_store
+
+CONFIG_DIR = Path.home() / ".ceph-aiops"
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+ENV_FILE = CONFIG_DIR / ".env"
+
+# Ceph mgr Dashboard defaults.
+DEFAULT_MGR_PORT = 8443
+DEFAULT_USERNAME = "admin"
+
+# Legacy env-var prefix/suffix; also used by the migration helper.
+SECRET_ENV_PREFIX = "CEPH_"  # nosec B105 — env-var name, not a secret
+SECRET_ENV_SUFFIX = "_PASSWORD"  # nosec B105 — env-var name, not a secret
+
+_log = logging.getLogger("ceph-aiops.config")
+
+
+def _secret_env_key(name: str) -> str:
+    """Legacy per-target password env var name, e.g. CEPH_LAB1_PASSWORD."""
+    return f"{SECRET_ENV_PREFIX}{name.upper().replace('-', '_')}{SECRET_ENV_SUFFIX}"
+
+
+def _resolve_secret(name: str) -> str:
+    """Return a target's password: encrypted store first, then legacy env var."""
+    if has_store():
+        try:
+            return get_secret(name)
+        except SecretStoreError:
+            pass  # fall through to legacy env var
+    legacy = os.environ.get(_secret_env_key(name))
+    if legacy:
+        _log.warning(
+            "Using plaintext env var %s. Migrate to the encrypted store with "
+            "'ceph-aiops secret migrate'.",
+            _secret_env_key(name),
+        )
+        return legacy
+    raise OSError(
+        f"No password for target '{name}'. Add one with "
+        f"'ceph-aiops secret set {name}' (stored encrypted), or run "
+        f"'ceph-aiops init'."
+    )
+
+
+@dataclass(frozen=True)
+class TargetConfig:
+    """A connection target for one Ceph cluster's mgr Dashboard REST API.
+
+    The password is sourced from the encrypted secret store (see ``password``),
+    never the config file. ``host`` is the active mgr host/FQDN; ``port``
+    defaults to ``8443``; ``username`` (default ``admin``) is the Dashboard
+    account and is not a secret.
+    """
+
+    name: str
+    host: str
+    port: int = DEFAULT_MGR_PORT
+    username: str = DEFAULT_USERNAME
+    verify_ssl: bool = True
+
+    @property
+    def password(self) -> str:
+        return _resolve_secret(self.name)
+
+    @property
+    def base_url(self) -> str:
+        return f"https://{self.host}:{self.port}"
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Top-level application config."""
+
+    targets: tuple[TargetConfig, ...] = ()
+
+    def get_target(self, name: str) -> TargetConfig:
+        for t in self.targets:
+            if t.name == name:
+                return t
+        available = ", ".join(t.name for t in self.targets) or "(none)"
+        raise KeyError(f"Target '{name}' not found. Available: {available}")
+
+    @property
+    def default_target(self) -> TargetConfig:
+        if not self.targets:
+            raise ValueError("No targets configured. Check config.yaml")
+        return self.targets[0]
+
+
+def load_config(config_path: Path | None = None) -> AppConfig:
+    """Load config from YAML; the password comes from the encrypted store."""
+    path = config_path or CONFIG_FILE
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Config file not found: {path}\n"
+            f"Run 'ceph-aiops init' to set up a Ceph cluster target and store its "
+            f"password encrypted, or create {CONFIG_FILE} with a 'targets' list."
+        )
+
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    targets = tuple(
+        TargetConfig(
+            name=t["name"],
+            host=t["host"],
+            port=t.get("port", DEFAULT_MGR_PORT),
+            username=t.get("username", DEFAULT_USERNAME),
+            verify_ssl=t.get("verify_ssl", True),
+        )
+        for t in raw.get("targets", [])
+    )
+
+    return AppConfig(targets=targets)