ceph-aiops 0.1.0__tar.gz

ceph_aiops-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+*.egg-info/

ceph_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to ceph-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — preview
+
+Initial preview release: governed AI-ops for **Ceph** via the ceph-mgr Dashboard
+REST API, with a bundled governance harness. Works against vanilla ceph-mgr
+(cephadm / Proxmox-hosted / MicroCeph) — no croit, no Kubernetes.
+**Mock-validated only — not yet verified against a live cluster.**
+
+### Added
+
+- **35 MCP tools** (17 read, 18 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **Health** — `cluster_health` (flagship RCA: per active HEALTH_WARN/ERR
+    check → plain-language cause + suggested action), `cluster_status`
+    (`ceph -s` summary).
+  - **OSD** — `osd_tree`, `osd_df` (most-full first + near/backfill-full flags),
+    `osd_perf` (slowest first); `cluster_flag_set` (low, undo — noout/noscrub/
+    nobackfill/norecover), `osd_reweight` (med, undo → prior weight; 0.0=drain),
+    `osd_mark_in` (med, undo), `osd_mark_out` (high, dry-run — drains data),
+    `osd_purge` (high, dry-run — irreversible).
+  - **PG** — `pg_summary` (state histogram + non-active+clean), `pg_dump_stuck`
+    (stuck PGs + implicated OSDs), `scrub_status` (overdue scrub/deep-scrub);
+    `trigger_scrub` (low), `trigger_deep_scrub` (low).
+  - **Pool** — `pool_ls`, `pool_df` (usable capacity = raw ÷ size);
+    `set_pool_quota` (med, undo), `set_pool_pg_num` (med, undo),
+    `set_pool_autoscale` (med, undo), `pool_create` (med), `set_pool_size`
+    (high, dry-run — replica change forces data movement), `pool_delete`
+    (high, dry-run — destroys all data).
+  - **RBD** — `rbd_ls`; `rbd_image_create` (med), `rbd_snapshot_create` (low),
+    `rbd_image_delete` (high, dry-run), `rbd_snapshot_delete` (high, dry-run).
+  - **CephFS / RGW** — `cephfs_status` (MDS ranks + "behind on trimming" +
+    client count), `rgw_status` (daemons + buckets + LARGE_OMAP /
+    unsharded-index findings).
+  - **Cluster-ops** — `mon_status` (quorum / out-of-quorum), `mgr_status`
+    (active/standbys/modules), `slow_ops` (blocked requests by OSD),
+    `capacity_forecast` (days-to-nearfull); `throttle_recovery` (med, undo —
+    `osd_max_backfills` / `osd_recovery_max_active`).
+- **JWT authentication** — username + password exchanged for a short-lived JWT
+  at `POST /api/auth` against the mgr Dashboard (`https://<host>:8443`); the mgr
+  **dashboard** module must be enabled.
+- **Encrypted secret store** — the Dashboard password is stored encrypted in
+  `~/.ceph-aiops/secrets.enc` (Fernet + scrypt); never plaintext on disk. Legacy
+  `CEPH_<TARGET>_PASSWORD` env var honoured as a fallback.
+- **CLI** (`ceph-aiops`) — `init` wizard, `secret` management, `doctor`,
+  `overview`, and the `health` / `osd` sub-commands.
+- **Teaching connection layer** — JWT login with centralised, human-readable
+  error translation (e.g. dashboard-module-not-enabled, auth failure).
+
+### Known limitations
+
+- Preview / mock-only: multi-node rebalance behaviour and the write ops are
+  unverified against a real Ceph cluster. Fastest live check: a single-node
+  MicroCeph running `ceph-aiops doctor`.
+- The ceph-mgr Dashboard API has no ETag / pagination, so this tool exposes none.
+- Out of scope by design (v0.1.0): RGW multisite, NFS-Ganesha exports, and
+  cephadm orchestrator host management.

ceph_aiops-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wei <zhouwei008@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ceph_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: ceph-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for Ceph (ceph-mgr Dashboard REST): HEALTH_WARN root-cause analysis, OSD/PG/pool/RBD/CephFS/RGW operations, and destructive-op guardrails with a built-in governance harness (audit, budget, undo, risk tiers)
+Author-email: wei <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<2.0,>=1.10
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: rich<16.0,>=13.0
+Requires-Dist: typer<1.0,>=0.12
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.AIops-tools/ceph-aiops -->
+
+# Ceph AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the Ceph project or any storage vendor.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **Ceph** — talks to a vanilla **ceph-mgr Dashboard REST API**
+(HTTPS `:8443`, username + password exchanged for a short-lived JWT at
+`POST /api/auth`) with a **built-in governance harness**: unified audit log,
+policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. Works against stock ceph-mgr — **cephadm**,
+**Proxmox-hosted Ceph**, or **MicroCeph** — with **no croit and no Kubernetes
+dependency**. Self-contained: no external skill-family dependency.
+**Preview — mock-validated only, not yet verified against a live cluster.**
+
+## What it does
+
+The flagship analysis, plus the guarded reads and writes around it:
+
+- **`cluster_health` — HEALTH_WARN/ERR root-cause analysis.** Instead of echoing
+  raw check codes (`PG_DEGRADED`, `OSD_NEARFULL`, `SLOW_OPS`, `MON_DOWN`,
+  `LARGE_OMAP_OBJECTS`, …), it turns each *active* check into plain language:
+  **what it means, the likely cause, and the suggested next action**. This is the
+  differentiator vs the hobby Ceph MCPs that just proxy `ceph -s`.
+- **Governed destructive ops.** The operations operators actually fear —
+  `osd_purge`, `pool_delete`, `set_pool_size`, `rbd_image_delete` — carry
+  **dry-run + double-confirm** and a **high** risk tier; reversible tuning
+  (`osd_reweight`, `throttle_recovery`, `cluster_flag_set`, pool quota/pg_num/
+  autoscale) records an **undo descriptor** capturing the prior state.
+
+## What works
+
+- **CLI** (`ceph-aiops ...`): `init`, `overview`, `health detail`/`health status`,
+  `osd tree/df/reweight/out/purge`, `secret set/list/rm/migrate/rotate-password`,
+  `doctor`, `mcp`. `osd out` and `osd purge` require `--dry-run` + double confirm.
+- **MCP server** (`ceph-aiops mcp` or `ceph-aiops-mcp`): the full **35 tools**
+  (17 read, 18 write), every one wrapped with the bundled `@governed_tool`
+  harness. The CLI is a convenience subset; the MCP surface is the whole tool.
+- **Encrypted credentials**: the Dashboard password lives in an encrypted store
+  `~/.ceph-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**.
+  Unlock with a master password from `CEPH_AIOPS_MASTER_PASSWORD` (MCP/CI) or an
+  interactive prompt (CLI).
+- **Reversibility**: reversible writes capture the prior state and record an
+  inverse undo descriptor (e.g. `osd_reweight` → prior weight, `set_pool_quota`
+  → prior quota, `throttle_recovery` → prior backfill/recovery settings).
+- **Safety**: destructive ops (`osd_purge`, `osd_mark_out`, `pool_delete`,
+  `set_pool_size`, `rbd_image_delete`, `rbd_snapshot_delete`) are `high` risk
+  with `dry_run` and CLI double confirmation.
+
+## Capability matrix (35 MCP tools)
+
+| Group | Tools | Count | R/W |
+|-------|-------|:-----:|:---:|
+| **Health** | `cluster_health` (flagship RCA), `cluster_status` | 2 | read |
+| **OSD** | `osd_tree`, `osd_df`, `osd_perf` | 3 | read |
+| | `cluster_flag_set` (low, undo), `osd_reweight` (med, undo), `osd_mark_in` (med, undo) | 3 | write |
+| | `osd_mark_out` (high, dry-run), `osd_purge` (high, dry-run) | 2 | write |
+| **PG** | `pg_summary`, `pg_dump_stuck`, `scrub_status` | 3 | read |
+| | `trigger_scrub` (low), `trigger_deep_scrub` (low) | 2 | write |
+| **Pool** | `pool_ls`, `pool_df` | 2 | read |
+| | `set_pool_quota` (med, undo), `set_pool_pg_num` (med, undo), `set_pool_autoscale` (med, undo), `pool_create` (med) | 4 | write |
+| | `set_pool_size` (high, dry-run), `pool_delete` (high, dry-run) | 2 | write |
+| **RBD** | `rbd_ls` | 1 | read |
+| | `rbd_image_create` (med), `rbd_snapshot_create` (low) | 2 | write |
+| | `rbd_image_delete` (high, dry-run), `rbd_snapshot_delete` (high, dry-run) | 2 | write |
+| **CephFS / RGW** | `cephfs_status`, `rgw_status` | 2 | read |
+| **Cluster-ops** | `mon_status`, `mgr_status`, `slow_ops`, `capacity_forecast` | 4 | read |
+| | `throttle_recovery` (med, undo) | 1 | write |
+
+Totals: **35 tools — 17 read, 18 write.**
+
+## Quick start
+
+```bash
+uv tool install ceph-aiops          # or: pipx install ceph-aiops
+ceph-aiops init                     # wizard: add a mgr target + store the Dashboard password (encrypted)
+ceph-aiops doctor                   # JWT login + mgr-dashboard reachability
+ceph-aiops overview                 # HEALTH status + active checks + OSD up/in
+ceph-aiops health detail            # decode the active HEALTH_WARN/ERR checks (RCA)
+ceph-aiops osd df                   # per-OSD utilization, most-full first, near/backfill-full flags
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export CEPH_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+ceph-aiops-mcp
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier,
+  approver, rationale) is logged to `~/.ceph-aiops/audit.db` (relocatable
+  via `CEPH_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops (purge/delete/replica
+  change) can require a named approver
+  (`CEPH_AUDIT_APPROVED_BY` / `CEPH_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes record an inverse descriptor.
+
+## Supported scope & limitations
+
+- **Deployments**: vanilla ceph-mgr with the **dashboard** module enabled —
+  cephadm, Proxmox-hosted Ceph, or MicroCeph. **No croit, no Kubernetes
+  dependency.**
+- **Ceph has no ETag / pagination** on the Dashboard API, so this tool exposes
+  none — nothing is missing, the upstream API simply doesn't offer them.
+- **Preview / mock-only.** Behaviour is validated against mocked Dashboard
+  responses. The cheapest **live** check is a single-node **MicroCeph**
+  (`snap install microceph` → bootstrap → loop-file OSDs) running
+  `ceph-aiops doctor`; a 3-node Vagrant cluster exercises real rebalance
+  behaviour. Multi-node rebalance and the write ops are **unverified against a
+  real cluster**.
+
+## Missing a capability?
+
+RGW multisite, per-daemon config sprawl, NFS-Ganesha exports, orchestrator
+(cephadm) host management — not here yet. **Open an issue or send a PR** — feedback
+and contributions are welcome.

ceph_aiops-0.1.0/README.md

@@ -0,0 +1,121 @@
+<!-- mcp-name: io.github.AIops-tools/ceph-aiops -->
+
+# Ceph AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by the Ceph project or any storage vendor.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **Ceph** — talks to a vanilla **ceph-mgr Dashboard REST API**
+(HTTPS `:8443`, username + password exchanged for a short-lived JWT at
+`POST /api/auth`) with a **built-in governance harness**: unified audit log,
+policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. Works against stock ceph-mgr — **cephadm**,
+**Proxmox-hosted Ceph**, or **MicroCeph** — with **no croit and no Kubernetes
+dependency**. Self-contained: no external skill-family dependency.
+**Preview — mock-validated only, not yet verified against a live cluster.**
+
+## What it does
+
+The flagship analysis, plus the guarded reads and writes around it:
+
+- **`cluster_health` — HEALTH_WARN/ERR root-cause analysis.** Instead of echoing
+  raw check codes (`PG_DEGRADED`, `OSD_NEARFULL`, `SLOW_OPS`, `MON_DOWN`,
+  `LARGE_OMAP_OBJECTS`, …), it turns each *active* check into plain language:
+  **what it means, the likely cause, and the suggested next action**. This is the
+  differentiator vs the hobby Ceph MCPs that just proxy `ceph -s`.
+- **Governed destructive ops.** The operations operators actually fear —
+  `osd_purge`, `pool_delete`, `set_pool_size`, `rbd_image_delete` — carry
+  **dry-run + double-confirm** and a **high** risk tier; reversible tuning
+  (`osd_reweight`, `throttle_recovery`, `cluster_flag_set`, pool quota/pg_num/
+  autoscale) records an **undo descriptor** capturing the prior state.
+
+## What works
+
+- **CLI** (`ceph-aiops ...`): `init`, `overview`, `health detail`/`health status`,
+  `osd tree/df/reweight/out/purge`, `secret set/list/rm/migrate/rotate-password`,
+  `doctor`, `mcp`. `osd out` and `osd purge` require `--dry-run` + double confirm.
+- **MCP server** (`ceph-aiops mcp` or `ceph-aiops-mcp`): the full **35 tools**
+  (17 read, 18 write), every one wrapped with the bundled `@governed_tool`
+  harness. The CLI is a convenience subset; the MCP surface is the whole tool.
+- **Encrypted credentials**: the Dashboard password lives in an encrypted store
+  `~/.ceph-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on disk**.
+  Unlock with a master password from `CEPH_AIOPS_MASTER_PASSWORD` (MCP/CI) or an
+  interactive prompt (CLI).
+- **Reversibility**: reversible writes capture the prior state and record an
+  inverse undo descriptor (e.g. `osd_reweight` → prior weight, `set_pool_quota`
+  → prior quota, `throttle_recovery` → prior backfill/recovery settings).
+- **Safety**: destructive ops (`osd_purge`, `osd_mark_out`, `pool_delete`,
+  `set_pool_size`, `rbd_image_delete`, `rbd_snapshot_delete`) are `high` risk
+  with `dry_run` and CLI double confirmation.
+
+## Capability matrix (35 MCP tools)
+
+| Group | Tools | Count | R/W |
+|-------|-------|:-----:|:---:|
+| **Health** | `cluster_health` (flagship RCA), `cluster_status` | 2 | read |
+| **OSD** | `osd_tree`, `osd_df`, `osd_perf` | 3 | read |
+| | `cluster_flag_set` (low, undo), `osd_reweight` (med, undo), `osd_mark_in` (med, undo) | 3 | write |
+| | `osd_mark_out` (high, dry-run), `osd_purge` (high, dry-run) | 2 | write |
+| **PG** | `pg_summary`, `pg_dump_stuck`, `scrub_status` | 3 | read |
+| | `trigger_scrub` (low), `trigger_deep_scrub` (low) | 2 | write |
+| **Pool** | `pool_ls`, `pool_df` | 2 | read |
+| | `set_pool_quota` (med, undo), `set_pool_pg_num` (med, undo), `set_pool_autoscale` (med, undo), `pool_create` (med) | 4 | write |
+| | `set_pool_size` (high, dry-run), `pool_delete` (high, dry-run) | 2 | write |
+| **RBD** | `rbd_ls` | 1 | read |
+| | `rbd_image_create` (med), `rbd_snapshot_create` (low) | 2 | write |
+| | `rbd_image_delete` (high, dry-run), `rbd_snapshot_delete` (high, dry-run) | 2 | write |
+| **CephFS / RGW** | `cephfs_status`, `rgw_status` | 2 | read |
+| **Cluster-ops** | `mon_status`, `mgr_status`, `slow_ops`, `capacity_forecast` | 4 | read |
+| | `throttle_recovery` (med, undo) | 1 | write |
+
+Totals: **35 tools — 17 read, 18 write.**
+
+## Quick start
+
+```bash
+uv tool install ceph-aiops          # or: pipx install ceph-aiops
+ceph-aiops init                     # wizard: add a mgr target + store the Dashboard password (encrypted)
+ceph-aiops doctor                   # JWT login + mgr-dashboard reachability
+ceph-aiops overview                 # HEALTH status + active checks + OSD up/in
+ceph-aiops health detail            # decode the active HEALTH_WARN/ERR checks (RCA)
+ceph-aiops osd df                   # per-OSD utilization, most-full first, near/backfill-full flags
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export CEPH_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+ceph-aiops-mcp
+```
+
+## Governance
+
+Every MCP tool passes through the bundled `@governed_tool` harness:
+
+- **Audit** — every call (params, result, status, duration, risk tier,
+  approver, rationale) is logged to `~/.ceph-aiops/audit.db` (relocatable
+  via `CEPH_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers** — graduated autonomy; high-risk ops (purge/delete/replica
+  change) can require a named approver
+  (`CEPH_AUDIT_APPROVED_BY` / `CEPH_AUDIT_RATIONALE`).
+- **Undo recording** — reversible writes record an inverse descriptor.
+
+## Supported scope & limitations
+
+- **Deployments**: vanilla ceph-mgr with the **dashboard** module enabled —
+  cephadm, Proxmox-hosted Ceph, or MicroCeph. **No croit, no Kubernetes
+  dependency.**
+- **Ceph has no ETag / pagination** on the Dashboard API, so this tool exposes
+  none — nothing is missing, the upstream API simply doesn't offer them.
+- **Preview / mock-only.** Behaviour is validated against mocked Dashboard
+  responses. The cheapest **live** check is a single-node **MicroCeph**
+  (`snap install microceph` → bootstrap → loop-file OSDs) running
+  `ceph-aiops doctor`; a 3-node Vagrant cluster exercises real rebalance
+  behaviour. Multi-node rebalance and the write ops are **unverified against a
+  real cluster**.
+
+## Missing a capability?
+
+RGW multisite, per-daemon config sprawl, NFS-Ganesha exports, orchestrator
+(cephadm) host management — not here yet. **Open an issue or send a PR** — feedback
+and contributions are welcome.

ceph_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,57 @@
+# Ceph AIops v0.1.0 — preview
+
+Governed AI-ops for **Ceph** via the **ceph-mgr Dashboard REST API** for AI
+agents, with a built-in governance harness (audit, policy, token/runaway
+budget, undo-token recording, graduated risk tiers) and an encrypted credential
+store. Standalone — no external skill-family dependency. Works against vanilla
+ceph-mgr (cephadm / Proxmox-hosted / MicroCeph) — no croit, no Kubernetes.
+
+> **Preview / mock-only.** All behaviour is validated against mocked Dashboard
+> REST responses; it has not been run against a live Ceph cluster. The fastest
+> live check is a single-node MicroCeph running `ceph-aiops doctor`.
+
+## Highlights
+
+- **35 MCP tools** (17 read, 18 write), every one wrapped with `@governed_tool`:
+  - **Health** — `cluster_health` (flagship: per active HEALTH_WARN/ERR check →
+    plain-language cause + suggested action), `cluster_status`.
+  - **OSD** — `osd_tree`, `osd_df` (most-full first + near/backfill-full flags),
+    `osd_perf`; writes `cluster_flag_set`, `osd_reweight`, `osd_mark_in`,
+    `osd_mark_out` (high), `osd_purge` (high).
+  - **PG** — `pg_summary`, `pg_dump_stuck`, `scrub_status`; `trigger_scrub`,
+    `trigger_deep_scrub`.
+  - **Pool** — `pool_ls`, `pool_df` (usable capacity = raw ÷ size); writes
+    `set_pool_quota`, `set_pool_pg_num`, `set_pool_autoscale`, `pool_create`,
+    `set_pool_size` (high), `pool_delete` (high).
+  - **RBD** — `rbd_ls`; `rbd_image_create`, `rbd_snapshot_create`,
+    `rbd_image_delete` (high), `rbd_snapshot_delete` (high).
+  - **CephFS / RGW** — `cephfs_status`, `rgw_status`.
+  - **Cluster-ops** — `mon_status`, `mgr_status`, `slow_ops`,
+    `capacity_forecast`; `throttle_recovery` (the #1 tuning ask —
+    `osd_max_backfills` / `osd_recovery_max_active`).
+- **HEALTH_WARN root-cause analysis** — `cluster_health` decodes each active
+  check code into cause + action, the differentiator vs raw `ceph -s` proxies.
+- **JWT auth** — username + password exchanged for a short-lived JWT at
+  `POST /api/auth`; the mgr **dashboard** module must be enabled.
+- **Encrypted secret store** (`~/.ceph-aiops/secrets.enc`, Fernet + scrypt) —
+  never plaintext on disk; legacy `CEPH_<TARGET>_PASSWORD` env fallback.
+- **CLI** with an `init` onboarding wizard, `secret` management, and `doctor`.
+- **Dry-run + double-confirm** on the destructive ops operators fear
+  (`osd_purge`, `osd_mark_out`, `pool_delete`, `set_pool_size`,
+  `rbd_image_delete`); reversible writes record an undo descriptor.
+
+## Install
+
+```bash
+uv tool install ceph-aiops
+ceph-aiops init
+ceph-aiops doctor
+```
+
+## Caveats
+
+- Preview / mock-only: multi-node rebalance behaviour and the write ops are
+  unverified against a real cluster.
+- The Dashboard API has no ETag / pagination, so this tool exposes none.
+- Out of scope for v0.1.0: RGW multisite, NFS-Ganesha exports, and cephadm
+  orchestrator host management.

ceph_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,79 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by the Ceph project or the Ceph Foundation.** Product and trademark
+names belong to their owners. Source is publicly auditable under the MIT license.
+
+## Reporting Vulnerabilities
+
+Report privately via a GitHub Security Advisory on
+[github.com/AIops-tools/Ceph-AIops](https://github.com/AIops-tools/Ceph-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target ceph-mgr Dashboard passwords live **encrypted** in
+  `~/.ceph-aiops/secrets.enc` (Fernet/AES-128 + scrypt-derived key; chmod
+  600), never in `config.yaml` and never in source. The master password is
+  never stored — only a per-store random salt and the ciphertext are on disk.
+- A legacy plaintext env var `CEPH_<TARGET_NAME_UPPER>_PASSWORD` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `ceph-aiops secret migrate`).
+- The password is exchanged for a short-lived **JWT** at `POST /api/auth`; only
+  the token is sent on subsequent requests (Bearer), and it is refreshed once on
+  a 401. The password is held only in memory, never logged or echoed; the config
+  file holds only host, port, username, and TLS settings.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`ceph_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.ceph-aiops/`
+  (relocatable via `CEPH_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`CEPH_MAX_TOOL_CALLS` /
+  `CEPH_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption (e.g. polling a slow
+  session).
+- **Graduated risk tiers** — `~/.ceph-aiops/rules.yaml` `risk_tiers` gate
+  writes by environment/tag; the highest tiers require a recorded approver.
+- **Undo-token recording** — reversible writes capture the BEFORE state and
+  record an inverse descriptor (e.g. `osd_reweight`→restore prior weight,
+  `cluster_flag_set`→toggle the flag back, `throttle_recovery`→restore prior
+  backfill/recovery limits) so the change can be rolled back.
+
+### State-Changing Operations
+Destructive writes — `osd_mark_out`, `osd_purge`, `set_pool_size`, `pool_delete`,
+`rbd_image_delete`, `rbd_snapshot_delete` — are `risk_level=high`, accept a
+`dry_run` preview, and (under `risk_tiers`) require a recorded approver
+(`CEPH_AUDIT_APPROVED_BY` + `CEPH_AUDIT_RATIONALE`). The CLI additionally
+double-confirms `osd out` and `osd purge` and supports `--dry-run`. Reversible
+medium/low writes capture before-state and, where a safe inverse exists, record
+an undo token. Ceph has no ETag/If-Match and its list endpoints return full
+arrays, so there is no optimistic-concurrency token to manage.
+
+### SSL/TLS Verification
+`verify_ssl` defaults to true; disable only for self-signed lab certificates.
+
+### Prompt-Injection Protection
+All server-returned text (pool/OSD names, PG ids, health check messages, RGW
+bucket names) is passed through a `sanitize()` truncate + control-character strip
+before reaching the agent.
+
+### Network Scope
+No webhooks, no telemetry, no outbound calls beyond the configured ceph-mgr
+Dashboard REST API endpoint. No post-install scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r ceph_aiops/ mcp_server/
+uv run ruff check .
+```
+
+## Supported Versions
+
+The latest released version receives security fixes. This is a preview (0.x);
+pin a version in production.

ceph_aiops-0.1.0/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-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-0.1.0/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-0.1.0/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-0.1.0/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))