apache-aiops 0.2.0__py3-none-any.whl

apache_aiops/mcp_server/tools/undo.py

@@ -0,0 +1,204 @@
+"""Undo executor — list recorded inverse descriptors and APPLY them.
+
+Every governed write records a replayable inverse descriptor (tool + params) to
+``undo.db``. This module closes the loop: ``undo_apply`` looks up a recorded
+descriptor and dispatches it to the named governed tool, so the inverse runs on
+the SAME governance path as any other call (audited and budget-checked, and — if
+the inverse itself is destructive — recorded under its own risk tier). Whether
+the inverse *should* run is the caller's decision, exactly as for the original
+write; ``undo_apply`` records it either way.
+
+Note: recorded ``undo_params`` are the redacted safe-params captured at record
+time, so an inverse that would need a secret value cannot be replayed here — by
+design, inverses in this line key off ids/names, not credentials.
+"""
+
+import json
+from typing import Any, Optional
+
+from apache_aiops.governance import governed_tool
+from apache_aiops.governance.undo import get_undo_store
+from apache_aiops.mcp_server._shared import mcp, tool_errors
+
+
+def _resolve_tool(name: str) -> Any:
+    """Return the governed callable registered under ``name`` (or None).
+
+    The CLI reaches this through ``undo apply``, whose process only imports
+    ``apache_aiops.mcp_server.tools.undo`` — every other tool module is imported lazily inside
+    its own CLI command and so is absent here. Without forcing a full load,
+    ``undo_apply`` would fail with "inverse tool not registered" for every write
+    tool when driven from the CLI (the MCP entry point loads all modules, so it
+    never hit this). If the first lookup misses, import ``apache_aiops.mcp_server.server`` —
+    which registers every ``@mcp.tool()`` as an import side effect — and retry.
+    Imported lazily to avoid the undo↔server cycle.
+    """
+    tool = mcp._tool_manager._tools.get(name)
+    if tool is None:
+        import apache_aiops.mcp_server.server  # noqa: F401 — registers all tools as a side effect
+
+        tool = mcp._tool_manager._tools.get(name)
+    return getattr(tool, "fn", None) if tool else None
+
+
+@mcp.tool()
+@governed_tool(risk_level="low")
+@tool_errors("dict")
+def undo_list(limit: int = 50, target: Optional[str] = None) -> dict:
+    """[READ] List recorded, not-yet-applied undo tokens (most recent first).
+
+    Each entry names the original tool, the inverse tool that ``undo_apply``
+    would run, and a human note. Use the ``undoId`` with ``undo_apply``.
+
+    One extra row is read so ``truncated`` is measured rather than guessed from
+    the row count matching the limit; when it is true, older tokens exist.
+
+    Each entry carries ``effectVerified``. False means the original write
+    lost its response, so the change it reverses is PROBABLE, not confirmed —
+    check the live state before applying, and do not report the result as a
+    restore of a state that may never have been reached.
+
+    Args:
+        limit: Max rows to return (default 50, capped at 500).
+        target: Unused (undo state is host-local); accepted for CLI uniformity.
+    """
+    requested = max(1, min(int(limit), 500))
+    raw = get_undo_store().list(status="recorded", limit=requested + 1)
+    truncated = len(raw) > requested
+    rows = raw[:requested]
+    return {
+        "count": len(rows),
+        "returned": len(rows),
+        "limit": requested,
+        "truncated": truncated,
+        "undos": [
+            {
+                "undoId": r["undo_id"],
+                "ts": r["ts"],
+                "originalTool": r["tool"],
+                "inverseTool": r["undo_tool"],
+                "note": r.get("note", ""),
+                "effectVerified": bool(r.get("effect_verified", 1)),
+            }
+            for r in rows
+        ],
+    }
+
+
+def _origin_target(rec: dict) -> Optional[str]:
+    """The target the ORIGINAL write ran against, read from its recorded params.
+
+    Without this the replay goes to whatever target the caller names — in
+    practice the config's first entry — so on a multi-target config the inverse
+    runs against the wrong host. It only *looks* harmless because the resource
+    usually does not exist there; when two hosts both hold a resource with the
+    same name the inverse succeeds on the wrong one, silently.
+
+    Caught live on 2026-08-03 in container-host-aiops: a ``stop_container``
+    recorded against a Podman target replayed against a Portainer target.
+
+    A ``target`` in ``orig_params`` also means the original call accepted one,
+    so the fallback cannot hand a keyword to a tool that has no such parameter.
+    """
+    raw = rec.get("orig_params") or ""
+    try:
+        orig = json.loads(raw) if raw else {}
+    except (ValueError, TypeError):
+        return None  # unreadable: fall back to the caller/default, as before
+    if not isinstance(orig, dict):
+        return None
+    value = orig.get("target")
+    return value if isinstance(value, str) and value else None
+
+
+@mcp.tool()
+@governed_tool(risk_level="medium")
+@tool_errors("dict")
+def undo_apply(undo_id: str, dry_run: bool = False, target: Optional[str] = None) -> dict:
+    """[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
+
+    The inverse runs through its own governed tool, so it is audited under its
+    own risk tier. Pass dry_run=True to preview the inverse call without
+    executing it. A token can only be applied once.
+
+    Args:
+        undo_id: The undoId from undo_list (or an ``_undo_id`` in a write result).
+        dry_run: If True, preview the inverse tool + params without running it.
+        target: Passed through to the inverse tool when it accepts a target.
+    """
+    store = get_undo_store()
+    rec = store.get(undo_id)
+    if not rec:
+        raise ValueError(f"Unknown undo id '{undo_id}'. Run undo_list to see available tokens.")
+    if rec["status"] != "recorded":
+        raise ValueError(
+            f"Undo '{undo_id}' is already '{rec['status']}' — a token can only be applied once."
+        )
+
+    inverse_tool = rec["undo_tool"]
+    # Unreadable parameters must stop the replay, not be replaced with {}.
+    # Defaulting dispatched the inverse tool with NO ARGUMENTS: for a tool whose
+    # parameters all have defaults that runs a real, unintended operation, and
+    # dry_run previewed it as a legitimate no-arg inverse. Refusing is the only
+    # honest answer — the recorded intent is gone, so there is nothing to apply.
+    raw = rec["undo_params"]
+    try:
+        params = json.loads(raw) if raw else {}
+    except (ValueError, TypeError) as exc:
+        raise ValueError(
+            f"Undo '{undo_id}' has unreadable recorded parameters, so its inverse "
+            f"cannot be replayed. Inspect the row in undo.db and re-run the "
+            f"inverse tool '{inverse_tool}' by hand if the change still needs "
+            f"reversing."
+        ) from exc
+    if not isinstance(params, dict):
+        raise ValueError(
+            f"Undo '{undo_id}' recorded parameters of type "
+            f"'{type(params).__name__}' rather than an object, so its inverse "
+            f"cannot be replayed. Re-run the inverse tool '{inverse_tool}' by hand."
+        )
+
+    fn = _resolve_tool(inverse_tool)
+    if fn is None:
+        raise ValueError(
+            f"Inverse tool '{inverse_tool}' is not registered on this server; cannot apply."
+        )
+
+    effect_verified = bool(rec.get("effect_verified", 1))
+    if dry_run:
+        return {
+            "dryRun": True,
+            "undoId": undo_id,
+            "effectVerified": effect_verified,
+            "wouldApply": {"tool": inverse_tool, "params": params},
+        }
+
+    call_params = dict(params)
+    if "target" not in call_params:
+        chosen = target if target is not None else _origin_target(rec)
+        if chosen is not None:
+            call_params["target"] = chosen
+    result = fn(**call_params)
+
+    # Only mark applied when the inverse did not itself return an error dict.
+    if not (isinstance(result, dict) and result.get("error")):
+        store.mark(undo_id, "applied")
+        applied = True
+    else:
+        applied = False
+
+    return {
+        "undoId": undo_id,
+        "applied": applied,
+        "effectVerified": effect_verified,
+        "inverseTool": inverse_tool,
+        "result": result,
+        "note": (
+            ""
+            if effect_verified
+            else "The original write lost its response, so it was never confirmed "
+            "to have taken effect. This inverse ran regardless; report the "
+            "CURRENT server state, not a restore that may have had nothing "
+            "to restore."
+        ),
+    }

apache_aiops/ops/__init__.py

@@ -0,0 +1 @@
+"""Apache HTTP Server operational logic."""

apache_aiops/ops/httpd.py

@@ -0,0 +1,81 @@
+"""Read-only Apache HTTP Server diagnosis."""
+
+from __future__ import annotations
+
+from apache_aiops.connection import ApacheConnection
+
+
+def version(conn: ApacheConnection) -> dict:
+    return conn.command("-v")
+
+
+def build(conn: ApacheConnection) -> dict:
+    return conn.command("-V")
+
+
+def runtime_config(conn: ApacheConnection) -> dict:
+    return conn.command("-t", "-D", "DUMP_RUN_CFG")
+
+
+def config_includes(conn: ApacheConnection) -> dict:
+    return conn.command("-t", "-D", "DUMP_INCLUDES")
+
+
+def compiled_modules(conn: ApacheConnection) -> dict:
+    return conn.command("-l")
+
+
+def static_directives(conn: ApacheConnection) -> dict:
+    return conn.command("-L")
+
+
+def server_status(conn: ApacheConnection) -> dict:
+    return conn.server_status()
+
+
+def error_log(conn: ApacheConnection, limit: int = 50) -> dict:
+    return conn.error_log(limit)
+
+
+def access_status(conn: ApacheConnection, limit: int = 200) -> dict:
+    return conn.access_status(limit)
+
+
+def config_check(conn: ApacheConnection) -> dict:
+    return conn.command("configtest")
+
+
+def vhosts(conn: ApacheConnection) -> dict:
+    return conn.command("-S")
+
+
+def modules(conn: ApacheConnection) -> dict:
+    return conn.command("-M")
+
+
+def probe(conn: ApacheConnection) -> dict:
+    return conn.probe()
+
+
+def diagnose(conn: ApacheConnection) -> dict:
+    probes = {}
+    checks = [
+        ("version", lambda: version(conn)),
+        ("config", lambda: config_check(conn)),
+        ("vhosts", lambda: vhosts(conn)),
+        ("modules", lambda: modules(conn)),
+    ]
+    if conn.target.probe_url:
+        checks.append(("http", lambda: probe(conn)))
+    for name, call in checks:
+        try:
+            probes[name] = {"data": call(), "error": None}
+        except Exception as exc:
+            probes[name] = {"data": None, "error": f"{type(exc).__name__}: {exc}"}
+    failed = [name for name, result in probes.items() if result["error"] is not None]
+    return {
+        "probes": probes,
+        "failedProbes": failed,
+        "complete": not failed,
+        "httpProbeConfigured": bool(conn.target.probe_url),
+    }

apache_aiops-0.2.0.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: apache-aiops
+Version: 0.2.0
+Summary: Governed Apache HTTP Server diagnosis for config, virtual hosts, modules and HTTP health.
+Author-email: Wei Zhou <zhouwei008@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: mcp[cli]<3.0,>=2.0
+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/apache-aiops -->
+# Apache AIops
+
+A dedicated, governed MCP server, CLI and skill for Apache HTTP Server with 17 MCP tools. It uses Apache's own `apachectl` diagnostics, optional operator-configured HTTP health and `mod_status` URLs, and bounded reads of an operator-configured error log plus a privacy-preserving access-log status summary. Every call is audited and budgeted by the vendored governance harness.
+
+## What it checks
+
+- Apache version, config syntax, parsed virtual hosts and loaded modules.
+- Build options and parsed runtime configuration.
+- Parsed config include tree, compiled modules and directives from static modules.
+- Optional machine-readable `mod_status` metrics, bounded error-log tail and privacy-preserving access-status summary.
+- Optional HTTP health status without downloading the response body.
+- `apache_diagnose` correlates the checks and preserves failures as errors with `data: null`.
+
+## Setup from source
+
+Requires Python 3.11+, `uv`, and `apachectl` on the operator host. Run `uv sync --dev`, `uv run apache-aiops init`, then `uv run apache-aiops doctor`. Manual `~/.apache-aiops/config.yaml`:
+
+```yaml
+targets:
+  - name: local
+    apachectl_bin: apachectl
+    probe_url: http://127.0.0.1/health
+    status_url: http://127.0.0.1/server-status?auto
+    error_log: /var/log/apache2/error.log
+    access_log: /var/log/apache2/access.log
+    timeout: 10
+    verify_ssl: true
+```
+
+Run `uv run apache-aiops diagnose`. The MCP entry point is `uv run apache-aiops-mcp`. The optional HTTP probe is configured by the operator, not chosen by a tool caller. TLS verification is enabled by default, and `ca_file` accepts a custom CA PEM.
+
+## Scope and verification
+
+`graceful-reload` first runs `configtest`, supports dry-run and two CLI confirmations, and reports an unknown final outcome even if the command returned: existing workers may still serve the old config. It has no safe inverse when the prior config file is not snapshotted. Vhost editing, TLS certificate management and module changes remain outside this release. See [verification](docs/VERIFICATION.md). Missing operations and live-environment feedback are welcome as issues or PRs.

apache_aiops-0.2.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+apache_aiops/__init__.py,sha256=z7L-cyDLucsZJXRxQ1HRKCriITkx0acvE4I8_QQI8Us,233
+apache_aiops/config.py,sha256=3WeQnVGJUl1osfY8PQrk81aJKHDUsZzVdNmSNcyZPag,2840
+apache_aiops/connection.py,sha256=m-lrIxtreB1cWXyVKfpOhQax5SgVbLsLdDLiOAOoovc,9384
+apache_aiops/cli/__init__.py,sha256=WUzjLZLugDpUuLvX4zUYAh04f_qO-v3xF2TdMerFm0Y,204
+apache_aiops/cli/_common.py,sha256=veEs4a8Vtf6X2TNh2eiYfvjSy15kufTle1mqVIyd_H4,5156
+apache_aiops/cli/_root.py,sha256=VFAkpknlHj1DCUKntaaLeh9wZaVQKp5QZWbxw4F4hck,6438
+apache_aiops/cli/undo.py,sha256=_0wrb1IGwzvnVqlPNaWDTQGGsep1rVTtW5_zQ1zuRiE,2052
+apache_aiops/governance/__init__.py,sha256=AzqEiNuKb4yKkhZ-6W_AUbV7uhqEsOTMzc89qZOUwT4,1713
+apache_aiops/governance/audit.py,sha256=TcpBwszPsToLQ8q_7As-yloXt-Ys677-_yp3BuCXsAY,19534
+apache_aiops/governance/budget.py,sha256=1auVcTtTDDA4qh-NGQUIRwr5QzZSk1l_TWer4AxQbc8,8961
+apache_aiops/governance/decorators.py,sha256=kpbaE7clZr59EAjM69hfi8STbRGOmIm7E6kLRsTU8_c,23302
+apache_aiops/governance/outcome.py,sha256=Hc882_A7t68nePxsOtUwflazn9KztXmOOBNKXo6n3W0,4376
+apache_aiops/governance/paths.py,sha256=jKInopiPU6hlZ9IjRfPo-zYryirKDBGpIdF7DS9bX0o,714
+apache_aiops/governance/patterns.py,sha256=JrVtLlN_3lkZc5LrI4i2gyNlaITkwUgBcTgWRApN5j4,15747
+apache_aiops/governance/policy.py,sha256=w4uKVpICVZxbXDpjiSH0N6iz8IBGCKPtFwX-ogCX9l8,2369
+apache_aiops/governance/sanitize.py,sha256=EV4jv0DUM-dzwiurGiDVZdtv9I3DgzCy-iAXwih9pBE,3310
+apache_aiops/governance/undo.py,sha256=aIYGsFKbpmHqseLx_fU5LM4F3C3AoEed9IEJ41hYUpU,9522
+apache_aiops/mcp_server/__init__.py,sha256=GSkSfzs3HjgUTUTY4OyO7pisvGDHGTlgQ-QovC4jwdA,43
+apache_aiops/mcp_server/_annotations.py,sha256=L8U5e4abQByPsT1FTV5Wgig146Vpdlx9s1eCtCXaYTI,2830
+apache_aiops/mcp_server/_shared.py,sha256=EuKfq_pWCqiN5qKvs_zLwQF9oO4dj5OfihjR5JkeaN4,2065
+apache_aiops/mcp_server/server.py,sha256=CCqvaXZlj6c8tq9OYb7AbhfN3rst-H776qjxikR6dZ0,392
+apache_aiops/mcp_server/tools/__init__.py,sha256=AZOqmTsbMg1fh8IsC9fv0NSDdkNA_ohgiyueeO5kjAo,76
+apache_aiops/mcp_server/tools/httpd.py,sha256=LMcFp-a_LOO8O9aCSEcxdUa65eVAgYsvjSsVFL57QxQ,4887
+apache_aiops/mcp_server/tools/undo.py,sha256=smJqNDMfmPD27xS9roquP7xPZMlc-92Lren1as-sJzU,8606
+apache_aiops/ops/__init__.py,sha256=rNjTzAXjJOzYJSALVVQrdX1pdM_0XlWCtIqIItLFpv4,44
+apache_aiops/ops/httpd.py,sha256=-jIfOgb1eDoGUhvaHUwQWqlLDMNHcg8_WzD1iyLmoaU,2098
+apache_aiops-0.2.0.dist-info/METADATA,sha256=f_iIgHfp-xbYErRJGoO9GtgKy-ZvGBAQ3uuEKBEDH5I,2686
+apache_aiops-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+apache_aiops-0.2.0.dist-info/entry_points.txt,sha256=id-ymyzTFNGeKgCWtxZunb2zhaz0On7inowXgfcHTIs,109
+apache_aiops-0.2.0.dist-info/licenses/LICENSE,sha256=-aN-YMNjW-2HFH71T7ohVfCJf9XeNX0MSVcPFpsgs_8,1083
+apache_aiops-0.2.0.dist-info/RECORD,,

apache_aiops-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

apache_aiops-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+apache-aiops = apache_aiops.cli:app
+apache-aiops-mcp = apache_aiops.mcp_server.server:main

apache_aiops-0.2.0.dist-info/licenses/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.