proxy-aiops 0.1.0__tar.gz

proxy_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

proxy_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

proxy_aiops-0.1.0/.gitignore

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

proxy_aiops-0.1.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to proxy-aiops are documented here. This project adheres
+to [Semantic Versioning](https://semver.org/).
+
+## v0.1.0 — 2026-07-17
+
+Initial preview release: governed AI-ops for **Traefik**, **Caddy** and
+**HAProxy** reverse proxies / load balancers, with a bundled governance
+harness. One MCP server spans all three platforms via a per-target `platform`
+field; an explicit support matrix raises teaching errors for ops a platform
+cannot do (never a silent no-op).
+**Mock-validated only — not yet verified against a live proxy.**
+
+### Added
+
+- **26 MCP tools** (21 read, 5 write), every one wrapped with the bundled
+  `@governed_tool` harness (audit, policy, token/runaway budget, undo,
+  risk-tiers):
+  - **Status (read)** — `proxy_overview`, `version_info`, `list_entrypoints`.
+  - **Routes (read)** — `list_routes` (normalised hosts/paths across
+    platforms), `route_detail`, `find_route` (static host/path match).
+  - **Services (read)** — `list_services`, `service_detail`, `list_upstreams`
+    (server-level up/down/maint/drain + check info), `upstream_detail`,
+    `list_middlewares`.
+  - **Certificates (read)** — `list_certificates` (TLS domain inventory +
+    optional bounded live handshake probe).
+  - **Traffic (read)** — `traffic_stats`, `error_counters` (traefik /metrics
+    text parsed per status code; haproxy Data Plane stats per class).
+  - **Config (read)** — `config_snapshot`, `search_config`, `get_config_value`.
+  - **Flagship analyses (read)** — `backend_health_rca`, `cert_expiry_sweep`,
+    `error_rate_rca`, `route_conflict_analysis` — transparent heuristics that
+    report their numbers, not a black-box verdict.
+  - **Writes** — caddy `set_config_value` (med, prior subtree captured →
+    undo restores it), `delete_config_path` (**high**, subtree captured → undo
+    re-creates it), `load_config` (**high**, full prior config snapshotted →
+    undo re-loads it); haproxy `set_server_state` (med, ready/drain/maint,
+    undo restores prior admin state), `set_server_weight` (med, undo restores
+    prior weight). Every write takes a `dry_run` preview; high-risk writes
+    require an approver.
+- **Platform abstraction with a support matrix** — a name-keyed registry maps
+  each target's `platform` (`traefik` / `caddy` / `haproxy`) to its auth style
+  + REST resource paths, and unsupported ops raise **teaching errors**:
+  traefik writes point at its providers, haproxy config edits point at the
+  runtime writes, caddy error counters point at access logs.
+- **Encrypted secret store** — the haproxy Data Plane API password (required)
+  or an optional Basic-auth credential for traefik/caddy is stored encrypted
+  in `~/.proxy-aiops/secrets.enc` (Fernet + scrypt); never plaintext on disk.
+  Traefik/caddy targets without a secret are treated as unauthenticated
+  localhost endpoints. Legacy `PROXY_<TARGET>_SECRET` env var honoured as a
+  fallback.
+- **CLI** (`proxy-aiops`) — `init` platform-picking wizard (TLS-verify default
+  ON, seeds a starter rules.yaml with the dual-control high-risk tier),
+  `overview`, `routes list/show/find`, `services list/show/upstreams`,
+  `analyze health/errors/conflicts`, `certs --sweep`,
+  `config snapshot/search/get/set/delete` and `server state/weight`
+  (dry-run + double-confirm, executed through the governed twins so CLI writes
+  are audited + undo-recorded), `secret` management, and a `doctor`
+  connectivity check (health/info probe per platform).
+
+### Known limitations
+
+- Preview / mock-only: Traefik, Caddy and HAProxy responses are mocked and
+  need live verification; the modelled REST paths especially (the haproxy
+  runtime-server weight write in particular).
+- haproxy host/path routing lives in haproxy.cfg ACLs and is not statically
+  analysed; `route_conflict_analysis` covers dead-backend detection there.
+- **Missing a capability? Open an issue or PR** — contributions welcome.

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

proxy_aiops-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: proxy-aiops
+Version: 0.1.0
+Summary: Governed AI-ops for Traefik + Caddy + HAProxy reverse proxies / load balancers: routes, services, upstream health, TLS cert expiry sweep, 5xx error-rate RCA, route conflict analysis, and governed writes (caddy config, haproxy server state/weight) 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/proxy-aiops -->
+
+# Proxy AIops (preview)
+
+Governed, audited AI-ops for **Traefik**, **Caddy** and **HAProxy** reverse proxies / load balancers — for AI agents (via MCP) and humans (via CLI).
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy project, HAProxy Technologies, or the HAProxy project.** Traefik, Caddy and HAProxy are trademarks of their respective owners. MIT licensed.
+
+proxy-aiops speaks to three proxy platforms behind one MCP server — **Traefik**
+(its API under `/api/...`, metrics-text counters via `/metrics`), **Caddy** (the
+admin API, default `localhost:2019`) and **HAProxy** (the Data Plane API v2 under
+`/v2/...`, HTTP Basic auth) — with the **same tools working on all three**. Each
+target in the config names its own `platform`; a name-keyed platform registry
+selects the API shape (auth + resource paths), and an explicit **support matrix**
+raises teaching errors for ops a platform genuinely cannot do — e.g. Traefik
+writes point you at its providers (file, container labels, orchestrator CRDs), never
+a silent no-op.
+
+Every tool runs through a **built-in governance harness** (vendored, zero external
+dependency): audit log, token/call budget with runaway circuit-breaker, graduated
+risk-tier approval, undo-token recording, and output sanitisation.
+
+## Why this exists
+
+- **One server, three proxies** — Traefik, Caddy and HAProxy in a mixed edge,
+  spoken to through identical tool names. Adding another proxy later is a new
+  platform descriptor, not a rewrite.
+- **Read the whole edge** — version, entrypoints/listeners, routes (routers /
+  caddy routes / frontends) with parsed hosts+paths, services and server-level
+  upstream health, middlewares, TLS domain inventory, traffic/error counters,
+  and the live config tree (snapshot + search).
+- **Flagship RCA analyses** — transparent heuristics that show their numbers,
+  never a black-box verdict: `backend_health_rca` (down upstreams → cause class
+  L4/L6/L7/DNS/maint + action), `cert_expiry_sweep` (days-to-expiry buckets +
+  per-platform renewal hints), `error_rate_rca` (5xx share vs the fleet
+  baseline, dominant code → 502/503/504/500 cause), and
+  `route_conflict_analysis` (shadowed routes, dead routes, redirect loops).
+- **Governed writes** — caddy config `set` / `delete` / full `load` (the prior
+  subtree/config is fetched first, so the recorded undo replays a real restore)
+  and haproxy runtime server `state` (ready/drain/maint) and `weight` (undo
+  restores the prior value) — all with `dry_run` previews; delete/load are
+  **risk=high** behind an approver gate.
+
+## Tool inventory (26 tools)
+
+| Domain | Tools | # | Kind |
+|--------|-------|:-:|------|
+| **Status** | `proxy_overview`, `version_info`, `list_entrypoints` | 3 | read |
+| **Routes** | `list_routes`, `route_detail`, `find_route` | 3 | read |
+| **Services** | `list_services`, `service_detail`, `list_upstreams`, `upstream_detail`, `list_middlewares` | 5 | read |
+| **Certificates** | `list_certificates` | 1 | read |
+| **Traffic** | `traffic_stats`, `error_counters` | 2 | read |
+| **Config** | `config_snapshot`, `search_config`, `get_config_value` | 3 | read |
+| **Flagship analyses** | `backend_health_rca`, `cert_expiry_sweep`, `error_rate_rca`, `route_conflict_analysis` | 4 | read |
+| **Writes (caddy)** | `set_config_value` | 1 | write (**med**) |
+| **Writes (caddy)** | `delete_config_path`, `load_config` | 2 | write (**high**) |
+| **Writes (haproxy)** | `set_server_state`, `set_server_weight` | 2 | write (**med**) |
+
+Reversible writes record an inverse **undo descriptor** built from the real fetched
+before-state (`set_config_value` restores the prior subtree; `delete_config_path`
+re-creates it; `load_config` re-loads the snapshotted config; server state/weight
+restore the prior value). The undo params match each tool's own signature, so the
+descriptor replays as-is.
+
+### Per-platform support matrix
+
+| Capability | traefik | caddy | haproxy |
+|------------|:-------:|:-----:|:-------:|
+| Routes / services / upstream health | ✅ | ✅ | ✅ |
+| Middlewares list | ✅ | teaching note (inline handlers) | teaching note (haproxy.cfg) |
+| TLS cert inventory + expiry sweep | ✅ | ✅ | teaching note (.pem files) |
+| Error counters / error-rate RCA | ✅ (/metrics) | teaching note (no per-route counters) | ✅ (stats) |
+| Config snapshot / search | ✅ (rawdata, read-only) | ✅ | teaching note |
+| Config writes | teaching error → edit the **provider** | ✅ (the write surface) | teaching error → runtime writes |
+| Runtime server state / weight | teaching error → provider | teaching error → config tree | ✅ |
+
+Unsupported combinations **raise a teaching error that says what to use instead**
+— never a silent empty result.
+
+## Install
+
+```bash
+uv tool install proxy-aiops        # or: pipx install proxy-aiops
+```
+
+## Quick start
+
+```bash
+proxy-aiops init                     # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret
+proxy-aiops doctor                   # verify config, secrets, and connectivity
+proxy-aiops overview                 # one-shot: version + route/service counts + upstream health
+proxy-aiops routes list              # normalised route table
+proxy-aiops services upstreams       # server-level upstream health
+proxy-aiops analyze health           # backend/upstream health RCA
+proxy-aiops analyze errors           # 5xx error-rate RCA
+proxy-aiops analyze conflicts        # shadowed/dead routes, redirect loops
+proxy-aiops certs --sweep            # TLS cert expiry sweep (traefik/caddy)
+proxy-aiops server state app web1 drain --dry-run   # governed haproxy write preview
+proxy-aiops config set apps/http/servers/srv0 '{"listen":[":8080"]}' --dry-run
+```
+
+Run the MCP server (stdio) for an agent:
+
+```bash
+proxy-aiops mcp                      # or: proxy-aiops-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "proxy-aiops": {
+      "command": "uvx",
+      "args": ["--from", "proxy-aiops", "proxy-aiops-mcp"],
+      "env": { "PROXY_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+> **Env-block caveat**: the `env` block is only needed when a credential is
+> stored (haproxy always; traefik/caddy only behind Basic auth). MCP clients do
+> **not** inherit your shell profile — set `PROXY_AIOPS_MASTER_PASSWORD` (and
+> `PROXY_AIOPS_CONFIG` / `PROXY_AIOPS_HOME` if you relocated them) explicitly in
+> the client config, or the server cannot unlock `secrets.enc`.
+
+## Configuration
+
+`~/.proxy-aiops/config.yaml` (non-secret connection details only):
+
+```yaml
+targets:
+  - name: edge1
+    platform: traefik        # traefik | caddy | haproxy
+    base_url: http://192.0.2.10:8080
+    verify_ssl: true
+  - name: caddy1
+    platform: caddy
+    base_url: http://127.0.0.1:2019
+  - name: lb1
+    platform: haproxy
+    base_url: http://192.0.2.20:5555
+    username: dpapi          # Data Plane API user
+```
+
+The **secret** — the HAProxy Data Plane API password, or an optional Basic-auth
+password in front of Traefik/Caddy — is stored **encrypted** in
+`~/.proxy-aiops/secrets.enc` (Fernet + scrypt-derived key), never plaintext on
+disk. Traefik and Caddy commonly run unauthenticated on localhost, so their
+secret is **optional** (like a local socket); HAProxy's is required. Set it with
+`proxy-aiops secret set <target>` or the `init` wizard. The store is unlocked by
+a master password from `PROXY_AIOPS_MASTER_PASSWORD` (non-interactive/MCP/CI) or
+an interactive prompt (CLI on a TTY). A legacy plaintext env var
+`PROXY_<TARGET>_SECRET` is honoured as a fallback (migrate with
+`proxy-aiops secret migrate`).
+
+## Governance
+
+Every MCP tool is wrapped by `@governed_tool`:
+
+- **Audit** — every call is logged to `~/.proxy-aiops/audit.db` (tool, params with
+  secrets redacted, status, duration, risk tier, approver, rationale).
+- **Budget / runaway guard** — per-process token/call caps and a repeat-call circuit
+  breaker (`PROXY_MAX_TOOL_CALLS`, `PROXY_RUNAWAY_MAX`, …).
+- **Graduated risk tiers — secure by default** — with no
+  `~/.proxy-aiops/rules.yaml`, high-risk writes (`delete_config_path`,
+  `load_config`) require an approver: set `PROXY_AUDIT_APPROVED_BY` (and
+  `PROXY_AUDIT_RATIONALE`) before they will run. `init` seeds a starter
+  rules.yaml; an operator-authored rules file is honoured as-is.
+- **Undo recording** — reversible writes record an inverse descriptor to
+  `~/.proxy-aiops/undo.db` from the fetched before-state (recording only; an
+  external orchestrator executes it). Undo params match the target tool's own
+  signature, so the descriptor replays as-is.
+- **Sanitisation** — all proxy-returned text is bounded + control-character
+  sanitised before it reaches the agent.
+
+## Preview status
+
+- **Platforms**: Traefik (API + /metrics), Caddy (admin API), HAProxy (Data Plane
+  API v2).
+- **Preview — mock-validated only. Not run against a live proxy.** All behaviour is
+  validated against mocked JSON/metrics responses; the concrete REST paths are
+  modelled from each project's public API and need live verification. All three
+  platforms are free and self-hostable (a small container-compose lab with
+  traefik + caddy + haproxy/dataplaneapi is a one-evening setup), so
+  `proxy-aiops doctor` — a health/info probe per platform — is the fastest
+  live check.
+- **Routing note**: this tool operates reverse proxies / load balancers. Do NOT
+  use it for firewall rules — use firewall-aiops.
+- **Missing a capability?** Open an issue or PR at
+  [github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops)
+  — contributions and feedback welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

proxy_aiops-0.1.0/README.md

@@ -0,0 +1,197 @@
+<!-- mcp-name: io.github.AIops-tools/proxy-aiops -->
+
+# Proxy AIops (preview)
+
+Governed, audited AI-ops for **Traefik**, **Caddy** and **HAProxy** reverse proxies / load balancers — for AI agents (via MCP) and humans (via CLI).
+
+> **Disclaimer**: Community-maintained open-source project. **Not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy project, HAProxy Technologies, or the HAProxy project.** Traefik, Caddy and HAProxy are trademarks of their respective owners. MIT licensed.
+
+proxy-aiops speaks to three proxy platforms behind one MCP server — **Traefik**
+(its API under `/api/...`, metrics-text counters via `/metrics`), **Caddy** (the
+admin API, default `localhost:2019`) and **HAProxy** (the Data Plane API v2 under
+`/v2/...`, HTTP Basic auth) — with the **same tools working on all three**. Each
+target in the config names its own `platform`; a name-keyed platform registry
+selects the API shape (auth + resource paths), and an explicit **support matrix**
+raises teaching errors for ops a platform genuinely cannot do — e.g. Traefik
+writes point you at its providers (file, container labels, orchestrator CRDs), never
+a silent no-op.
+
+Every tool runs through a **built-in governance harness** (vendored, zero external
+dependency): audit log, token/call budget with runaway circuit-breaker, graduated
+risk-tier approval, undo-token recording, and output sanitisation.
+
+## Why this exists
+
+- **One server, three proxies** — Traefik, Caddy and HAProxy in a mixed edge,
+  spoken to through identical tool names. Adding another proxy later is a new
+  platform descriptor, not a rewrite.
+- **Read the whole edge** — version, entrypoints/listeners, routes (routers /
+  caddy routes / frontends) with parsed hosts+paths, services and server-level
+  upstream health, middlewares, TLS domain inventory, traffic/error counters,
+  and the live config tree (snapshot + search).
+- **Flagship RCA analyses** — transparent heuristics that show their numbers,
+  never a black-box verdict: `backend_health_rca` (down upstreams → cause class
+  L4/L6/L7/DNS/maint + action), `cert_expiry_sweep` (days-to-expiry buckets +
+  per-platform renewal hints), `error_rate_rca` (5xx share vs the fleet
+  baseline, dominant code → 502/503/504/500 cause), and
+  `route_conflict_analysis` (shadowed routes, dead routes, redirect loops).
+- **Governed writes** — caddy config `set` / `delete` / full `load` (the prior
+  subtree/config is fetched first, so the recorded undo replays a real restore)
+  and haproxy runtime server `state` (ready/drain/maint) and `weight` (undo
+  restores the prior value) — all with `dry_run` previews; delete/load are
+  **risk=high** behind an approver gate.
+
+## Tool inventory (26 tools)
+
+| Domain | Tools | # | Kind |
+|--------|-------|:-:|------|
+| **Status** | `proxy_overview`, `version_info`, `list_entrypoints` | 3 | read |
+| **Routes** | `list_routes`, `route_detail`, `find_route` | 3 | read |
+| **Services** | `list_services`, `service_detail`, `list_upstreams`, `upstream_detail`, `list_middlewares` | 5 | read |
+| **Certificates** | `list_certificates` | 1 | read |
+| **Traffic** | `traffic_stats`, `error_counters` | 2 | read |
+| **Config** | `config_snapshot`, `search_config`, `get_config_value` | 3 | read |
+| **Flagship analyses** | `backend_health_rca`, `cert_expiry_sweep`, `error_rate_rca`, `route_conflict_analysis` | 4 | read |
+| **Writes (caddy)** | `set_config_value` | 1 | write (**med**) |
+| **Writes (caddy)** | `delete_config_path`, `load_config` | 2 | write (**high**) |
+| **Writes (haproxy)** | `set_server_state`, `set_server_weight` | 2 | write (**med**) |
+
+Reversible writes record an inverse **undo descriptor** built from the real fetched
+before-state (`set_config_value` restores the prior subtree; `delete_config_path`
+re-creates it; `load_config` re-loads the snapshotted config; server state/weight
+restore the prior value). The undo params match each tool's own signature, so the
+descriptor replays as-is.
+
+### Per-platform support matrix
+
+| Capability | traefik | caddy | haproxy |
+|------------|:-------:|:-----:|:-------:|
+| Routes / services / upstream health | ✅ | ✅ | ✅ |
+| Middlewares list | ✅ | teaching note (inline handlers) | teaching note (haproxy.cfg) |
+| TLS cert inventory + expiry sweep | ✅ | ✅ | teaching note (.pem files) |
+| Error counters / error-rate RCA | ✅ (/metrics) | teaching note (no per-route counters) | ✅ (stats) |
+| Config snapshot / search | ✅ (rawdata, read-only) | ✅ | teaching note |
+| Config writes | teaching error → edit the **provider** | ✅ (the write surface) | teaching error → runtime writes |
+| Runtime server state / weight | teaching error → provider | teaching error → config tree | ✅ |
+
+Unsupported combinations **raise a teaching error that says what to use instead**
+— never a silent empty result.
+
+## Install
+
+```bash
+uv tool install proxy-aiops        # or: pipx install proxy-aiops
+```
+
+## Quick start
+
+```bash
+proxy-aiops init                     # wizard: pick platform (traefik/caddy/haproxy) + optional encrypted secret
+proxy-aiops doctor                   # verify config, secrets, and connectivity
+proxy-aiops overview                 # one-shot: version + route/service counts + upstream health
+proxy-aiops routes list              # normalised route table
+proxy-aiops services upstreams       # server-level upstream health
+proxy-aiops analyze health           # backend/upstream health RCA
+proxy-aiops analyze errors           # 5xx error-rate RCA
+proxy-aiops analyze conflicts        # shadowed/dead routes, redirect loops
+proxy-aiops certs --sweep            # TLS cert expiry sweep (traefik/caddy)
+proxy-aiops server state app web1 drain --dry-run   # governed haproxy write preview
+proxy-aiops config set apps/http/servers/srv0 '{"listen":[":8080"]}' --dry-run
+```
+
+Run the MCP server (stdio) for an agent:
+
+```bash
+proxy-aiops mcp                      # or: proxy-aiops-mcp
+```
+
+### MCP client config
+
+```json
+{
+  "mcpServers": {
+    "proxy-aiops": {
+      "command": "uvx",
+      "args": ["--from", "proxy-aiops", "proxy-aiops-mcp"],
+      "env": { "PROXY_AIOPS_MASTER_PASSWORD": "your-master-password" }
+    }
+  }
+}
+```
+
+> **Env-block caveat**: the `env` block is only needed when a credential is
+> stored (haproxy always; traefik/caddy only behind Basic auth). MCP clients do
+> **not** inherit your shell profile — set `PROXY_AIOPS_MASTER_PASSWORD` (and
+> `PROXY_AIOPS_CONFIG` / `PROXY_AIOPS_HOME` if you relocated them) explicitly in
+> the client config, or the server cannot unlock `secrets.enc`.
+
+## Configuration
+
+`~/.proxy-aiops/config.yaml` (non-secret connection details only):
+
+```yaml
+targets:
+  - name: edge1
+    platform: traefik        # traefik | caddy | haproxy
+    base_url: http://192.0.2.10:8080
+    verify_ssl: true
+  - name: caddy1
+    platform: caddy
+    base_url: http://127.0.0.1:2019
+  - name: lb1
+    platform: haproxy
+    base_url: http://192.0.2.20:5555
+    username: dpapi          # Data Plane API user
+```
+
+The **secret** — the HAProxy Data Plane API password, or an optional Basic-auth
+password in front of Traefik/Caddy — is stored **encrypted** in
+`~/.proxy-aiops/secrets.enc` (Fernet + scrypt-derived key), never plaintext on
+disk. Traefik and Caddy commonly run unauthenticated on localhost, so their
+secret is **optional** (like a local socket); HAProxy's is required. Set it with
+`proxy-aiops secret set <target>` or the `init` wizard. The store is unlocked by
+a master password from `PROXY_AIOPS_MASTER_PASSWORD` (non-interactive/MCP/CI) or
+an interactive prompt (CLI on a TTY). A legacy plaintext env var
+`PROXY_<TARGET>_SECRET` is honoured as a fallback (migrate with
+`proxy-aiops secret migrate`).
+
+## Governance
+
+Every MCP tool is wrapped by `@governed_tool`:
+
+- **Audit** — every call is logged to `~/.proxy-aiops/audit.db` (tool, params with
+  secrets redacted, status, duration, risk tier, approver, rationale).
+- **Budget / runaway guard** — per-process token/call caps and a repeat-call circuit
+  breaker (`PROXY_MAX_TOOL_CALLS`, `PROXY_RUNAWAY_MAX`, …).
+- **Graduated risk tiers — secure by default** — with no
+  `~/.proxy-aiops/rules.yaml`, high-risk writes (`delete_config_path`,
+  `load_config`) require an approver: set `PROXY_AUDIT_APPROVED_BY` (and
+  `PROXY_AUDIT_RATIONALE`) before they will run. `init` seeds a starter
+  rules.yaml; an operator-authored rules file is honoured as-is.
+- **Undo recording** — reversible writes record an inverse descriptor to
+  `~/.proxy-aiops/undo.db` from the fetched before-state (recording only; an
+  external orchestrator executes it). Undo params match the target tool's own
+  signature, so the descriptor replays as-is.
+- **Sanitisation** — all proxy-returned text is bounded + control-character
+  sanitised before it reaches the agent.
+
+## Preview status
+
+- **Platforms**: Traefik (API + /metrics), Caddy (admin API), HAProxy (Data Plane
+  API v2).
+- **Preview — mock-validated only. Not run against a live proxy.** All behaviour is
+  validated against mocked JSON/metrics responses; the concrete REST paths are
+  modelled from each project's public API and need live verification. All three
+  platforms are free and self-hostable (a small container-compose lab with
+  traefik + caddy + haproxy/dataplaneapi is a one-evening setup), so
+  `proxy-aiops doctor` — a health/info probe per platform — is the fastest
+  live check.
+- **Routing note**: this tool operates reverse proxies / load balancers. Do NOT
+  use it for firewall rules — use firewall-aiops.
+- **Missing a capability?** Open an issue or PR at
+  [github.com/AIops-tools/Proxy-AIops](https://github.com/AIops-tools/Proxy-AIops)
+  — contributions and feedback welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

proxy_aiops-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,61 @@
+# Proxy AIops v0.1.0 — preview
+
+Governed AI-ops for **Traefik**, **Caddy** and **HAProxy** reverse proxies /
+load balancers 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. One MCP server spans all three platforms: a per-target `platform`
+field selects the API shape, and the same 26 tools work on Traefik (API +
+`/metrics`), Caddy (admin API) and HAProxy (Data Plane API v2, HTTP Basic).
+
+> **Not affiliated with, endorsed by, or sponsored by Traefik Labs, the Caddy
+> project, HAProxy Technologies, or the HAProxy project.** Traefik, Caddy and
+> HAProxy are trademarks of their respective owners.
+
+> **Preview / mock-only.** All behaviour is validated against mocked JSON /
+> metrics-text responses; it has **not** been run against a live proxy. The
+> concrete REST paths are modelled from each project's public API and need
+> live verification. All three platforms are free/self-hostable, so a small
+> lab is the easiest live check — `proxy-aiops doctor` is the fastest.
+
+## Highlights
+
+- **26 MCP tools** (21 read, 5 write), every one wrapped with `@governed_tool`:
+  - **Status** — `proxy_overview`, `version_info`, `list_entrypoints`.
+  - **Routes** — `list_routes` (hosts/paths normalised across platforms),
+    `route_detail`, `find_route`.
+  - **Services** — `list_services`, `service_detail`, `list_upstreams`,
+    `upstream_detail`, `list_middlewares`.
+  - **Certificates** — `list_certificates` (+ bounded live expiry probe).
+  - **Traffic** — `traffic_stats`, `error_counters`.
+  - **Config** — `config_snapshot`, `search_config`, `get_config_value`.
+  - **Writes** — caddy `set_config_value` / `delete_config_path` /
+    `load_config` (prior config captured → replayable undo), haproxy
+    `set_server_state` (ready/drain/maint) / `set_server_weight` (undo
+    restores the prior value). High-risk writes gate on an approver.
+- **Flagship analyses** (transparent heuristics that show their numbers):
+  - `backend_health_rca` — down upstreams per service with the failure class
+    (connection refused / L4 timeout / TLS / L7 check / DNS / maint) + action.
+  - `cert_expiry_sweep` — days-to-expiry buckets (expired / critical /
+    warning / ok) + per-platform renewal hints.
+  - `error_rate_rca` — per-service 5xx share vs the fleet baseline; the
+    dominant code maps to a cause (503 no-upstream / 502 conn-fail /
+    504 timeout / 500 app error).
+  - `route_conflict_analysis` — shadowed routes, dead routes (service missing
+    or zero servers up), redirect loops.
+- **Support matrix with teaching errors** — ops a platform cannot do fail fast
+  with what to use instead (traefik writes → its providers; caddy counters →
+  access logs; haproxy certs → the .pem pipeline). Never a silent no-op.
+- **Governance** — audit to `~/.proxy-aiops/audit.db`, budget/runaway guard,
+  secure-by-default approver gate for high-risk writes, undo descriptors built
+  from the real fetched before-state (replayable as-is), output sanitisation.
+
+## Install
+
+```bash
+uv tool install proxy-aiops
+proxy-aiops init && proxy-aiops doctor
+```
+
+Routing note: this tool operates reverse proxies / load balancers. Do NOT use
+it for firewall rules — use firewall-aiops.