minio-aiops 0.1.0__tar.gz

minio_aiops-0.1.0/.github/workflows/mcp-publish.yml

@@ -0,0 +1,55 @@
+name: mcp-publish
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish-mcp:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Wait for PyPI
+        # The release event also triggers the PyPI publish workflow; the MCP
+        # registry validates that the package version exists on PyPI, so poll
+        # until it has propagated (every 15s, up to 10 minutes).
+        run: |
+          python3 - <<'EOF'
+          import json
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          with open("server.json", encoding="utf-8") as f:
+              package = json.load(f)["packages"][0]
+          name, version = package["identifier"], package["version"]
+          url = f"https://pypi.org/pypi/{name}/{version}/json"
+          deadline = time.monotonic() + 600
+          while True:
+              try:
+                  with urllib.request.urlopen(url, timeout=10):
+                      print(f"{name}=={version} is available on PyPI.")
+                      sys.exit(0)
+              except (urllib.error.URLError, OSError) as exc:
+                  print(f"{name}=={version} not on PyPI yet ({exc}); "
+                        "retrying in 15s...")
+              if time.monotonic() >= deadline:
+                  sys.exit(f"Timed out after 10 minutes waiting for "
+                           f"{name}=={version} to appear on PyPI. "
+                           "Check the PyPI publish workflow, then re-run "
+                           "this workflow via workflow_dispatch.")
+              time.sleep(15)
+          EOF
+      - name: Install mcp-publisher
+        run: |
+          curl -sL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - name: Login to MCP Registry (GitHub OIDC)
+        run: ./mcp-publisher login github-oidc
+      - name: Publish server.json
+        run: ./mcp-publisher publish

minio_aiops-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC) — publishes from GitHub's runners with no API token,
+# sidestepping the local-IP / account new-project rate limit. Configure a matching
+# "trusted publisher" for this package on PyPI (see the repo release notes).
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

minio_aiops-0.1.0/.gitignore

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

minio_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to **minio-aiops** are documented here.
+
+## v0.1.0 — 2026-07-17
+
+Initial preview release: governed AI-ops for **MinIO** object storage over the
+S3 API (official SDK), the admin API, the unauthenticated health endpoints,
+and the cluster metrics endpoint — with a bundled governance harness.
+
+### Highlights
+
+- **Four flagship analyses** (cause + suggested action, thresholds as named
+  constants):
+  - `capacity_rca` — usable capacity vs used, offline drives/nodes, per-drive
+    hotspots, fill imbalance.
+  - `bucket_exposure_audit` — ranked findings: anonymous/public policy
+    statements (read/write), missing default encryption, versioning off, no
+    lifecycle.
+  - `lifecycle_gap_analysis` — unbounded noncurrent versions, incomplete
+    multipart uploads with no abort rule, large buckets with no lifecycle —
+    with a labelled reclaimable estimate.
+  - `healing_health` — heal backlog/errors + per-erasure-set write-quorum
+    risk and remaining drive-failure tolerance.
+- **29 MCP tools** (21 read, 8 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit / budget / risk-tier / undo).
+- **Guarded writes**: `set_bucket_policy`, `delete_bucket_policy`,
+  `set_versioning`, `set_lifecycle`, `delete_lifecycle`, `set_bucket_quota`
+  (all reversible — real prior state captured, undo recorded);
+  `bucket_delete` (high risk, refused unless verifiably empty, irreversible);
+  `remove_incomplete_uploads` (age-gated, priorState only). All writes take
+  `dry_run`.
+- **CLI**: `init` wizard (encrypted secret store, TLS prompts with lab hints,
+  seeds a secure-by-default `rules.yaml`), `doctor` (live/ready + S3 auth +
+  metrics reachability), `overview`, read groups (`health`, `capacity`,
+  `heal`, `bucket`) and guarded write commands with `--dry-run` +
+  double-confirm, delegated to the governed MCP twins (CLI writes are
+  audited).
+- **Metrics auth, both modes**: `MINIO_PROMETHEUS_AUTH_TYPE=public` scraped
+  directly; default `jwt` mode uses a bearer token derived from the stored
+  credentials.
+- **Encrypted credentials**: secret key in `~/.minio-aiops/secrets.enc`
+  (Fernet + scrypt), master password via `MINIO_AIOPS_MASTER_PASSWORD`;
+  legacy `MINIO_<TARGET>_SECRET_KEY` env fallback with `secret migrate`.
+
+### Known limitations
+
+- **Preview / mock-only** — validated against mocked SDK/HTTP responses, not
+  yet against a live server. Fastest live check: a single-node MinIO server
+  running `minio-aiops doctor`.
+- Incomplete-upload listing uses the SDK's core ListMultipartUploads call
+  (the public alias was removed upstream).
+- Out of scope for v0.1.0: site replication, object locking/legal hold, IAM
+  (users/policies) management, remote tiering.

minio_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.

minio_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: minio-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for MinIO object storage: capacity & usage RCA, bucket exposure audit, lifecycle/ILM gap analysis, healing & erasure-set health, and guarded bucket writes 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: minio<8.0,>=7.2
+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/minio-aiops -->
+
+# MinIO AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by MinIO, Inc. or any storage vendor.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **MinIO** object storage — for the homelab and small/medium
+self-hosted deployments where MinIO actually lives. Talks to the **S3 API**
+(official `minio` SDK, SigV4), the **admin API** (bucket quota, server info),
+the unauthenticated **health endpoints** (`/minio/health/live|ready|cluster`),
+and the **cluster metrics endpoint** (`/minio/v2/metrics/cluster`, bearer-token
+or public auth) — with a **built-in governance harness**: unified audit log,
+policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. Self-contained: no external skill-family
+dependency. **Preview — mock-validated only, not yet verified against a live
+server.**
+
+## What it does
+
+Four flagship analyses, plus the guarded reads and writes around them:
+
+- **`capacity_rca`** — capacity vs used, offline drives/nodes, per-drive
+  hotspots and imbalance → each finding as **cause + suggested action**
+  (nearfull/full thresholds are named constants, not magic).
+- **`bucket_exposure_audit`** — every bucket scored and **ranked** for
+  anonymous/public policy statements (read and, far worse, write), missing
+  default encryption, versioning off, no lifecycle.
+- **`lifecycle_gap_analysis`** — the storage ILM should be reclaiming but
+  isn't: versioned buckets with **no noncurrent expiry** (old bytes accrue
+  forever), **incomplete multipart uploads** with no abort rule (invisible
+  space), large buckets with no lifecycle — with a clearly-labelled
+  **reclaimable estimate**.
+- **`healing_health`** — heal backlog and per-erasure-set **write-quorum
+  risk**: how many more drive failures each set can tolerate, which sets are
+  healing, where heal errors are piling up.
+- **Governed writes.** Bucket policy / versioning / lifecycle / quota changes
+  capture the **real prior state** and record an **undo descriptor**;
+  `bucket_delete` is **refused unless the bucket is verifiably empty**
+  (including versions and delete markers) and `remove_incomplete_uploads`
+  only touches uploads older than a safety window.
+
+## What works
+
+- **CLI** (`minio-aiops ...`): `init`, `overview`, `doctor`, `health
+  check/status`, `capacity rca/usage`, `heal status/drives/nodes`, `bucket
+  ls/info/audit/ilm-gap/uploads` plus guarded writes (`bucket
+  versioning-set/policy-set/lifecycle-set/quota-set/purge-uploads/delete`),
+  `secret set/list/rm/migrate/rotate-password`, `mcp`. Destructive commands
+  take `--dry-run` and double-confirm.
+- **MCP server** (`minio-aiops mcp` or `minio-aiops-mcp`): the full **29
+  tools** (21 read, 8 write), every one wrapped with the bundled
+  `@governed_tool` harness. The CLI is a convenience subset; the MCP surface
+  is the whole tool. CLI writes delegate to the same governed functions, so
+  they are audited identically.
+- **Encrypted credentials**: the secret key lives in an encrypted store
+  `~/.minio-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on
+  disk**. Unlock with a master password from `MINIO_AIOPS_MASTER_PASSWORD`
+  (MCP/CI) or an interactive prompt (CLI).
+- **Metrics auth, both modes**: servers running
+  `MINIO_PROMETHEUS_AUTH_TYPE=public` are scraped directly; for the default
+  (`jwt`) mode the bearer token is **derived from the stored credentials** —
+  no extra secret to manage.
+- **Reversibility**: reversible writes capture prior state and record an
+  inverse undo descriptor (prior policy JSON, prior lifecycle XML, prior
+  versioning state, prior quota).
+
+## Capability matrix (29 MCP tools)
+
+| Group | Tools | Count | R/W |
+|-------|-------|:-----:|:---:|
+| **Health** | `health_live`, `health_ready`, `health_cluster`, `cluster_status`, `fleet_overview` | 5 | read |
+| **Capacity** | `capacity_rca` (flagship), `usage_by_bucket` | 2 | read |
+| **Healing** | `healing_health` (flagship), `drive_status`, `node_status` | 3 | read |
+| **Exposure / ILM** | `bucket_exposure_audit` (flagship), `lifecycle_gap_analysis` (flagship) | 2 | read |
+| **Buckets** | `bucket_ls`, `bucket_info`, `bucket_policy_get`, `bucket_lifecycle_get`, `bucket_versioning_get`, `bucket_quota_get`, `object_ls`, `incomplete_uploads_ls`, `server_info` | 9 | read |
+| **Writes** | `set_bucket_policy` (med, undo), `delete_bucket_policy` (med, undo), `set_versioning` (med, undo), `set_lifecycle` (med, undo), `delete_lifecycle` (med, undo), `set_bucket_quota` (med, undo) | 6 | write |
+| | `bucket_delete` (**high**, dry-run, empty-only, irreversible), `remove_incomplete_uploads` (med, dry-run, priorState only) | 2 | write |
+
+Totals: **29 tools — 21 read, 8 write.**
+
+## Quick start
+
+```bash
+uv tool install minio-aiops         # or: pipx install minio-aiops
+minio-aiops init                    # wizard: endpoint + access key; secret key stored encrypted
+minio-aiops doctor                  # live/ready + S3 auth + metrics reachability
+minio-aiops overview                # health + capacity headline + exposure headline
+minio-aiops capacity rca            # why is storage filling up, and what to do
+minio-aiops bucket audit            # ranked bucket-exposure findings
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export MINIO_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+minio-aiops-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "minio-aiops": {
+      "command": "uvx",
+      "args": ["--from", "minio-aiops", "minio-aiops-mcp"],
+      "env": { "MINIO_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+> **Env-block caveat**: MCP clients launch the server **without a TTY and
+> without your shell profile**, so the master password cannot be prompted for
+> and an `export` in `~/.zshrc` is not seen — it must be passed in the client's
+> `env` block (or the client process's environment) as above. Everything else
+> (targets, TLS, region, metrics mode) comes from `~/.minio-aiops/config.yaml`
+> written by `minio-aiops init`.
+
+## Configuration
+
+`~/.minio-aiops/config.yaml` (non-secret connection details only):
+
+```yaml
+targets:
+  - name: lab1
+    host: 192.0.2.10
+    port: 9000
+    access_key: minio-ops        # identifies the account; NOT the secret
+    secure: true                 # https (false for plain-http labs)
+    verify_ssl: true             # false for self-signed lab certs
+    region: ""                   # optional
+    metrics_public: false        # true when MINIO_PROMETHEUS_AUTH_TYPE=public
+```
+
+The secret key is stored with `minio-aiops secret set lab1` (encrypted; a
+legacy `MINIO_LAB1_SECRET_KEY` env var is honoured as a fallback with a
+migration warning).
+
+## 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 `~/.minio-aiops/audit.db` (relocatable
+  via `MINIO_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers, secure by default** — with no `rules.yaml`, high-risk ops
+  (`bucket_delete`) **require a named approver**
+  (`MINIO_AUDIT_APPROVED_BY` / `MINIO_AUDIT_RATIONALE`); `init` seeds an
+  explicit, editable starter policy.
+- **Undo recording** — reversible writes record an inverse descriptor built
+  from the captured prior state.
+
+## Supported scope & limitations
+
+- **Deployments**: any reasonably current MinIO server (single-node or
+  distributed/erasure-coded) reachable over its S3 port. Admin features
+  (quota, `server_info`) need admin-capable keys. Generic S3 services are not
+  a target: the health/metrics/admin surfaces used here are MinIO-specific.
+- **Metrics**: the capacity/healing RCAs read the **v2 cluster metrics**
+  endpoint; both `public` and bearer-token (default) auth modes are supported.
+- **Incomplete-upload listing** uses the SDK's core ListMultipartUploads call
+  (the public alias was removed from the SDK); it is exercised in tests and
+  documented in `connection.py`.
+- **Preview / mock-only.** Behaviour is validated against mocked SDK/HTTP
+  responses. The cheapest **live** check is a single-node MinIO server (a
+  container or the bare binary with a data directory) running
+  `minio-aiops doctor`. Erasure-set/healing findings need a multi-drive
+  deployment to observe for real.
+
+## Missing a capability?
+
+Site replication status, object locking / legal-hold governance, per-user /
+policy (IAM) management, tiering to remote storage — not here yet. **Open an
+issue or send a PR** — feedback and contributions are welcome.

minio_aiops-0.1.0/README.md

@@ -0,0 +1,176 @@
+<!-- mcp-name: io.github.AIops-tools/minio-aiops -->
+
+# MinIO AIops (preview)
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by MinIO, Inc. or any storage vendor.** Product and trademark names belong to their owners. MIT licensed.
+
+Governed AI-ops for **MinIO** object storage — for the homelab and small/medium
+self-hosted deployments where MinIO actually lives. Talks to the **S3 API**
+(official `minio` SDK, SigV4), the **admin API** (bucket quota, server info),
+the unauthenticated **health endpoints** (`/minio/health/live|ready|cluster`),
+and the **cluster metrics endpoint** (`/minio/v2/metrics/cluster`, bearer-token
+or public auth) — with a **built-in governance harness**: unified audit log,
+policy engine, token/runaway budget guard, undo-token recording, and
+graduated-autonomy risk tiers. Self-contained: no external skill-family
+dependency. **Preview — mock-validated only, not yet verified against a live
+server.**
+
+## What it does
+
+Four flagship analyses, plus the guarded reads and writes around them:
+
+- **`capacity_rca`** — capacity vs used, offline drives/nodes, per-drive
+  hotspots and imbalance → each finding as **cause + suggested action**
+  (nearfull/full thresholds are named constants, not magic).
+- **`bucket_exposure_audit`** — every bucket scored and **ranked** for
+  anonymous/public policy statements (read and, far worse, write), missing
+  default encryption, versioning off, no lifecycle.
+- **`lifecycle_gap_analysis`** — the storage ILM should be reclaiming but
+  isn't: versioned buckets with **no noncurrent expiry** (old bytes accrue
+  forever), **incomplete multipart uploads** with no abort rule (invisible
+  space), large buckets with no lifecycle — with a clearly-labelled
+  **reclaimable estimate**.
+- **`healing_health`** — heal backlog and per-erasure-set **write-quorum
+  risk**: how many more drive failures each set can tolerate, which sets are
+  healing, where heal errors are piling up.
+- **Governed writes.** Bucket policy / versioning / lifecycle / quota changes
+  capture the **real prior state** and record an **undo descriptor**;
+  `bucket_delete` is **refused unless the bucket is verifiably empty**
+  (including versions and delete markers) and `remove_incomplete_uploads`
+  only touches uploads older than a safety window.
+
+## What works
+
+- **CLI** (`minio-aiops ...`): `init`, `overview`, `doctor`, `health
+  check/status`, `capacity rca/usage`, `heal status/drives/nodes`, `bucket
+  ls/info/audit/ilm-gap/uploads` plus guarded writes (`bucket
+  versioning-set/policy-set/lifecycle-set/quota-set/purge-uploads/delete`),
+  `secret set/list/rm/migrate/rotate-password`, `mcp`. Destructive commands
+  take `--dry-run` and double-confirm.
+- **MCP server** (`minio-aiops mcp` or `minio-aiops-mcp`): the full **29
+  tools** (21 read, 8 write), every one wrapped with the bundled
+  `@governed_tool` harness. The CLI is a convenience subset; the MCP surface
+  is the whole tool. CLI writes delegate to the same governed functions, so
+  they are audited identically.
+- **Encrypted credentials**: the secret key lives in an encrypted store
+  `~/.minio-aiops/secrets.enc` (Fernet + scrypt) — **never plaintext on
+  disk**. Unlock with a master password from `MINIO_AIOPS_MASTER_PASSWORD`
+  (MCP/CI) or an interactive prompt (CLI).
+- **Metrics auth, both modes**: servers running
+  `MINIO_PROMETHEUS_AUTH_TYPE=public` are scraped directly; for the default
+  (`jwt`) mode the bearer token is **derived from the stored credentials** —
+  no extra secret to manage.
+- **Reversibility**: reversible writes capture prior state and record an
+  inverse undo descriptor (prior policy JSON, prior lifecycle XML, prior
+  versioning state, prior quota).
+
+## Capability matrix (29 MCP tools)
+
+| Group | Tools | Count | R/W |
+|-------|-------|:-----:|:---:|
+| **Health** | `health_live`, `health_ready`, `health_cluster`, `cluster_status`, `fleet_overview` | 5 | read |
+| **Capacity** | `capacity_rca` (flagship), `usage_by_bucket` | 2 | read |
+| **Healing** | `healing_health` (flagship), `drive_status`, `node_status` | 3 | read |
+| **Exposure / ILM** | `bucket_exposure_audit` (flagship), `lifecycle_gap_analysis` (flagship) | 2 | read |
+| **Buckets** | `bucket_ls`, `bucket_info`, `bucket_policy_get`, `bucket_lifecycle_get`, `bucket_versioning_get`, `bucket_quota_get`, `object_ls`, `incomplete_uploads_ls`, `server_info` | 9 | read |
+| **Writes** | `set_bucket_policy` (med, undo), `delete_bucket_policy` (med, undo), `set_versioning` (med, undo), `set_lifecycle` (med, undo), `delete_lifecycle` (med, undo), `set_bucket_quota` (med, undo) | 6 | write |
+| | `bucket_delete` (**high**, dry-run, empty-only, irreversible), `remove_incomplete_uploads` (med, dry-run, priorState only) | 2 | write |
+
+Totals: **29 tools — 21 read, 8 write.**
+
+## Quick start
+
+```bash
+uv tool install minio-aiops         # or: pipx install minio-aiops
+minio-aiops init                    # wizard: endpoint + access key; secret key stored encrypted
+minio-aiops doctor                  # live/ready + S3 auth + metrics reachability
+minio-aiops overview                # health + capacity headline + exposure headline
+minio-aiops capacity rca            # why is storage filling up, and what to do
+minio-aiops bucket audit            # ranked bucket-exposure findings
+```
+
+Run as an MCP server (stdio):
+
+```bash
+export MINIO_AIOPS_MASTER_PASSWORD=...   # unlock secrets non-interactively
+minio-aiops-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "minio-aiops": {
+      "command": "uvx",
+      "args": ["--from", "minio-aiops", "minio-aiops-mcp"],
+      "env": { "MINIO_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+> **Env-block caveat**: MCP clients launch the server **without a TTY and
+> without your shell profile**, so the master password cannot be prompted for
+> and an `export` in `~/.zshrc` is not seen — it must be passed in the client's
+> `env` block (or the client process's environment) as above. Everything else
+> (targets, TLS, region, metrics mode) comes from `~/.minio-aiops/config.yaml`
+> written by `minio-aiops init`.
+
+## Configuration
+
+`~/.minio-aiops/config.yaml` (non-secret connection details only):
+
+```yaml
+targets:
+  - name: lab1
+    host: 192.0.2.10
+    port: 9000
+    access_key: minio-ops        # identifies the account; NOT the secret
+    secure: true                 # https (false for plain-http labs)
+    verify_ssl: true             # false for self-signed lab certs
+    region: ""                   # optional
+    metrics_public: false        # true when MINIO_PROMETHEUS_AUTH_TYPE=public
+```
+
+The secret key is stored with `minio-aiops secret set lab1` (encrypted; a
+legacy `MINIO_LAB1_SECRET_KEY` env var is honoured as a fallback with a
+migration warning).
+
+## 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 `~/.minio-aiops/audit.db` (relocatable
+  via `MINIO_AIOPS_HOME`).
+- **Budget / runaway guard** — token and call budgets trip a circuit breaker.
+- **Risk tiers, secure by default** — with no `rules.yaml`, high-risk ops
+  (`bucket_delete`) **require a named approver**
+  (`MINIO_AUDIT_APPROVED_BY` / `MINIO_AUDIT_RATIONALE`); `init` seeds an
+  explicit, editable starter policy.
+- **Undo recording** — reversible writes record an inverse descriptor built
+  from the captured prior state.
+
+## Supported scope & limitations
+
+- **Deployments**: any reasonably current MinIO server (single-node or
+  distributed/erasure-coded) reachable over its S3 port. Admin features
+  (quota, `server_info`) need admin-capable keys. Generic S3 services are not
+  a target: the health/metrics/admin surfaces used here are MinIO-specific.
+- **Metrics**: the capacity/healing RCAs read the **v2 cluster metrics**
+  endpoint; both `public` and bearer-token (default) auth modes are supported.
+- **Incomplete-upload listing** uses the SDK's core ListMultipartUploads call
+  (the public alias was removed from the SDK); it is exercised in tests and
+  documented in `connection.py`.
+- **Preview / mock-only.** Behaviour is validated against mocked SDK/HTTP
+  responses. The cheapest **live** check is a single-node MinIO server (a
+  container or the bare binary with a data directory) running
+  `minio-aiops doctor`. Erasure-set/healing findings need a multi-drive
+  deployment to observe for real.
+
+## Missing a capability?
+
+Site replication status, object locking / legal-hold governance, per-user /
+policy (IAM) management, tiering to remote storage — not here yet. **Open an
+issue or send a PR** — feedback and contributions are welcome.

minio_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,39 @@
+# MinIO AIops v0.1.0 — preview
+
+Governed AI-ops for **MinIO** object storage for AI agents (MCP) and humans
+(CLI), with a bundled governance harness: audit, policy, token/runaway budget,
+undo recording, graduated risk tiers.
+
+> **Preview**: behaviour is validated against mocked SDK/HTTP responses; it
+> has not been run against a live MinIO server. The fastest live check is a
+> single-node server running `minio-aiops doctor`.
+
+## Surface
+
+- **29 MCP tools** (21 read, 8 write) over four access paths: S3 API (official
+  SDK), admin API (quota, server info), unauthenticated health endpoints, and
+  the cluster metrics endpoint (public or bearer-token auth — the token is
+  derived from the stored credentials).
+- **Flagship analyses**: `capacity_rca`, `bucket_exposure_audit`,
+  `lifecycle_gap_analysis`, `healing_health` — every finding is
+  cause + suggested action, thresholds are named constants.
+- **Guarded writes**: policy / versioning / lifecycle / quota (reversible,
+  prior state captured, undo recorded), `bucket_delete` (high risk, empty-only,
+  irreversible), `remove_incomplete_uploads` (age-gated purge, priorState
+  only). All writes take `dry_run`; destructive CLI commands double-confirm.
+
+## Governance
+
+- Unified audit log `~/.minio-aiops/audit.db` (relocatable via
+  `MINIO_AIOPS_HOME`); CLI writes route through the same governed functions.
+- Secure by default: with no `rules.yaml`, high-risk writes require a named
+  approver (`MINIO_AUDIT_APPROVED_BY`); `init` seeds an explicit starter
+  policy.
+- Encrypted secret store (`secrets.enc`, Fernet + scrypt) — no plaintext
+  secrets on disk.
+
+## Quality gates (this release)
+
+- 114 tests green (pytest), `ruff check` clean, bandit 0 Medium+ findings.
+- Every MCP tool carries the `_is_governed_tool` marker.
+- Undo descriptors are replay-tested against the target tool signatures.

minio_aiops-0.1.0/SECURITY.md

@@ -0,0 +1,82 @@
+# Security Policy
+
+## Disclaimer
+
+Community-maintained open-source project. **Not affiliated with, endorsed by, or
+sponsored by MinIO, Inc. or any storage vendor.** 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/MinIO-AIops](https://github.com/AIops-tools/MinIO-AIops/security/advisories)
+or email zhouwei008@gmail.com. Please do not open public issues for security
+reports.
+
+## Security Design
+
+### Credential Management
+- Per-target **secret keys** live **encrypted** in
+  `~/.minio-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 `MINIO_<TARGET_NAME_UPPER>_SECRET_KEY` is still
+  honoured as a fallback with a deprecation warning (migrate with
+  `minio-aiops secret migrate`).
+- S3/admin requests are **SigV4-signed** by the official SDK; the secret key
+  is held only in memory, never logged or echoed. The metrics bearer token is
+  derived from the credentials at request time (short TTL) and never stored.
+  The config file holds only host, port, access key, TLS/region/metrics
+  settings.
+
+### Governed Operations
+Every MCP tool runs through the bundled `@governed_tool` harness
+(`minio_aiops.governance`):
+- **Audit** — every call logged to a local SQLite DB under `~/.minio-aiops/`
+  (relocatable via `MINIO_AIOPS_HOME`), agent-attributed, secret-redacted.
+- **Token/runaway budget** — hard ceilings (`MINIO_MAX_TOOL_CALLS` /
+  `MINIO_MAX_TOOL_SECONDS`) plus an on-by-default guard that trips a tight
+  poll/retry loop, preventing unbounded API consumption.
+- **Graduated risk tiers, secure by default** — with no
+  `~/.minio-aiops/rules.yaml`, high-risk writes require a recorded approver;
+  the `init` wizard seeds an explicit, editable starter policy.
+- **Undo-token recording** — reversible writes capture the BEFORE state and
+  record an inverse descriptor (prior policy JSON, prior lifecycle XML, prior
+  versioning state, prior quota) so the change can be rolled back.
+
+### State-Changing Operations
+`bucket_delete` is `risk_level=high`, accepts a `dry_run` preview, requires a
+recorded approver (`MINIO_AUDIT_APPROVED_BY` + `MINIO_AUDIT_RATIONALE`) under
+the default policy, and is **refused unless the bucket is verifiably empty**
+(including noncurrent versions and delete markers) — this tool never
+mass-deletes objects to force a bucket empty. `remove_incomplete_uploads`
+only aborts uploads older than a safety window (default 7 days) and records
+priorState (count + sample). The CLI double-confirms both and supports
+`--dry-run` everywhere. All agent-supplied bucket names are validated against
+strict S3 naming rules before any request is built (the injection gate).
+
+### SSL/TLS Verification
+`secure` (https) and `verify_ssl` default to true; disable verification only
+for self-signed lab certificates.
+
+### Output Hygiene
+All server-returned text (bucket/object names, policy contents, error bodies,
+metric labels) 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 MinIO
+endpoint (S3/admin/health/metrics paths on the same origin). No post-install
+scripts or background services.
+
+## Static Analysis
+
+```bash
+uvx bandit -r minio_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.

minio_aiops-0.1.0/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP server package for minio-aiops."""