apache-aiops 0.2.0__py3-none-any.whl

apache_aiops/governance/paths.py

@@ -0,0 +1,23 @@
+"""Home-directory resolution for the governance harness.
+
+State lives under ``ops_home()`` — by default ``~/.apache-aiops``, overridable
+via the ``APACHE_AIOPS_HOME`` environment variable so an operator can relocate
+the audit / policy / budget / undo store.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_DEFAULT_HOME = "~/.apache-aiops"
+
+
+def ops_home() -> Path:
+    """Return the harness state directory, honoring ``APACHE_AIOPS_HOME``."""
+    return Path(os.environ.get("APACHE_AIOPS_HOME") or _DEFAULT_HOME).expanduser()
+
+
+def ops_path(*parts: str) -> Path:
+    """Resolve a file under the harness home, e.g. ``ops_path('audit.db')``."""
+    return ops_home().joinpath(*parts)

apache_aiops/governance/patterns.py

@@ -0,0 +1,396 @@
+"""L5 auto-remediation pattern engine.
+
+Implements the pattern matcher described in
+``docs/auto-remediation-patterns.md``. Patterns are loaded from
+``~/.apache-aiops/auto-remediation-patterns/*.yaml`` (hot-reload on mtime change)
+and consulted by the ``@governed_tool`` decorator on every call.
+
+Scope (PoC):
+  - Pattern loading and signature validation
+  - Action matching (is the current tool+params an armed pattern's action?)
+  - Rate limiting (per-pattern, per-target)
+  - Circuit breaker (3 consecutive validation failures → 24h disable)
+  - In-memory state — survives the MCP server process lifetime, NOT restarts
+
+Out of scope (future work — separate worker / daemon):
+  - Trigger matching against historical audit events
+  - Automatic action execution
+  - Validation post-step
+  - Persistent rate-limit / circuit-breaker state across restarts
+  - Approval channel for human signing
+
+Failure modes are deliberately fail-open: if pattern loading or matching
+errors out, the decorator falls through to normal behavior with a warning.
+A broken pattern file must not block all MCP tool calls.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from apache_aiops.governance.paths import ops_path
+
+_log = logging.getLogger("apache-aiops.patterns")
+
+_REQUIRED_TOP_LEVEL_KEYS = ("schema_version", "pattern_id", "classification", "action")
+_REQUIRED_CLASSIFICATION_KEYS = ("risk", "reversible", "repeatable")
+
+
+@dataclass(frozen=True)
+class Pattern:
+    """A loaded, signature-validated auto-remediation pattern."""
+
+    pattern_id: str
+    skill: str  # action.skill
+    tool: str  # action.tool
+    risk: str  # classification.risk — must be "low" to be armable
+    reversible: bool
+    repeatable: bool
+    expires_at: str  # ISO date or "" if never
+    rate_max_per_hour_per_target: int
+    rate_max_per_day_per_target: int
+    circuit_threshold: int  # consecutive failures → disable
+    circuit_disable_seconds: int
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_armable(self) -> bool:
+        """The hard preconditions per the design doc."""
+        return (
+            self.risk == "low"
+            and self.reversible is True
+            and self.repeatable is True
+            and not self.is_expired
+        )
+
+    @property
+    def is_expired(self) -> bool:
+        if not self.expires_at:
+            return False
+        try:
+            exp = datetime.fromisoformat(self.expires_at.replace("Z", "+00:00"))
+            if exp.tzinfo is None:
+                exp = exp.replace(tzinfo=UTC)
+            return datetime.now(tz=UTC) > exp
+        except (ValueError, TypeError):
+            _log.warning(
+                "pattern %s has malformed expires_at=%r — treating as expired",
+                self.pattern_id,
+                self.expires_at,
+            )
+            return True
+
+
+@dataclass
+class PatternMatch:
+    """Result of consulting the pattern engine for a tool call."""
+
+    pattern: Pattern
+    armed: bool  # True if rate limit + circuit breaker permit firing
+    reason: str = ""  # Human-readable explanation (esp. when not armed)
+
+
+@dataclass
+class _Counters:
+    """Per-(pattern_id, target) sliding-window state."""
+
+    arm_timestamps: list[float] = field(default_factory=list)  # epoch seconds
+    consecutive_failures: int = 0
+    disabled_until: float = 0.0  # epoch seconds
+
+
+class PatternEngine:
+    """Singleton pattern matcher integrated with @governed_tool."""
+
+    def __init__(self, patterns_dir: Path | str | None = None) -> None:
+        self._dir = (
+            Path(patterns_dir).expanduser()
+            if patterns_dir
+            else ops_path("auto-remediation-patterns")
+        )
+        self._patterns: dict[str, Pattern] = {}
+        self._mtimes: dict[Path, float] = {}
+        # _counters keyed by (pattern_id, target) — target may be ""
+        self._counters: dict[tuple[str, str], _Counters] = {}
+        self._lock = threading.Lock()
+        self._load()
+
+    # ── Pattern loading ───────────────────────────────────────────────
+
+    def _load(self) -> None:
+        """Load all *.yaml files from the patterns directory.
+
+        Bad files are skipped with a warning; good files replace prior state.
+        """
+        if not self._dir.exists():
+            self._patterns = {}
+            self._mtimes = {}
+            return
+
+        try:
+            import yaml
+        except ImportError:
+            _log.warning("PyYAML not installed — pattern engine disabled")
+            self._patterns = {}
+            return
+
+        new_patterns: dict[str, Pattern] = {}
+        new_mtimes: dict[Path, float] = {}
+        for path in sorted(self._dir.glob("*.yaml")):
+            try:
+                new_mtimes[path] = path.stat().st_mtime
+                with open(path) as fh:
+                    raw = yaml.safe_load(fh) or {}
+                pat = self._validate(raw, path)
+                if pat is not None:
+                    if pat.pattern_id in new_patterns:
+                        _log.warning(
+                            "duplicate pattern_id %r in %s — keeping first", pat.pattern_id, path
+                        )
+                        continue
+                    new_patterns[pat.pattern_id] = pat
+            except Exception:
+                _log.warning("failed to load pattern %s", path, exc_info=True)
+
+        self._patterns = new_patterns
+        self._mtimes = new_mtimes
+
+    def _maybe_reload(self) -> None:
+        """Reload if any file's mtime changed or new files appeared."""
+        if not self._dir.exists():
+            if self._patterns:
+                _log.warning("patterns dir deleted — clearing %d patterns", len(self._patterns))
+                self._patterns = {}
+                self._mtimes = {}
+            return
+        try:
+            current_files = set(self._dir.glob("*.yaml"))
+            tracked_files = set(self._mtimes.keys())
+            if current_files != tracked_files:
+                self._load()
+                return
+            for path in current_files:
+                if path.stat().st_mtime != self._mtimes.get(path, 0):
+                    self._load()
+                    return
+        except Exception:
+            _log.warning("failed to check patterns dir", exc_info=True)
+
+    @staticmethod
+    def _validate(raw: dict[str, Any], path: Path) -> Pattern | None:
+        """Validate signature + return a Pattern, or None if invalid."""
+        for k in _REQUIRED_TOP_LEVEL_KEYS:
+            if k not in raw:
+                _log.warning("pattern %s missing required key %r — skipped", path, k)
+                return None
+
+        if raw.get("schema_version") != 1:
+            _log.warning(
+                "pattern %s has schema_version=%r (expected 1) — skipped",
+                path,
+                raw.get("schema_version"),
+            )
+            return None
+
+        cls_block = raw.get("classification", {})
+        for k in _REQUIRED_CLASSIFICATION_KEYS:
+            if k not in cls_block:
+                _log.warning("pattern %s missing classification.%s — skipped", path, k)
+                return None
+
+        action = raw.get("action", {})
+        skill = action.get("skill")
+        tool = action.get("tool")
+        if not skill or not tool:
+            _log.warning("pattern %s missing action.skill or action.tool — skipped", path)
+            return None
+
+        # Patterns with status != approved are NOT armable. We still load them
+        # so callers can introspect, but is_armable returns False.
+        approval_status = (raw.get("approval", {}) or {}).get("status", "")
+        # Effectively makes risk=high if not approved — but cleaner to keep the
+        # explicit approval gate. We honor the YAML's classification.risk and let
+        # the approval status influence armability via signed_by check below.
+        signed_by = (raw.get("approval", {}) or {}).get("signed_by") or ""
+
+        rate = raw.get("rate_limit", {}) or {}
+        cb = raw.get("circuit_breaker", {}) or {}
+
+        # Force unsigned patterns to be non-armable by setting risk to a
+        # non-"low" sentinel. Loading still succeeds for inspection.
+        effective_risk = cls_block.get("risk", "")
+        # Both gates required: signed AND approved. A signed-but-rejected pattern
+        # must NOT be armable (yjs review 2026-05-06 — previously the OR-style
+        # check let signed-rejected slip through with original risk).
+        if not signed_by or approval_status != "approved":
+            effective_risk = "unsigned"
+
+        return Pattern(
+            pattern_id=str(raw.get("pattern_id")),
+            skill=str(skill),
+            tool=str(tool),
+            risk=str(effective_risk),
+            reversible=bool(cls_block.get("reversible", False)),
+            repeatable=bool(cls_block.get("repeatable", False)),
+            expires_at=str(raw.get("expires_at") or ""),
+            rate_max_per_hour_per_target=int(
+                rate.get("max_per_hour", rate.get("max_per_hour_per_host", 0)) or 0
+            ),
+            rate_max_per_day_per_target=int(
+                rate.get("max_per_day", rate.get("max_per_day_per_cluster", 0)) or 0
+            ),
+            circuit_threshold=int(cb.get("consecutive_validation_failures", 3) or 3),
+            circuit_disable_seconds=int(cb.get("disable_seconds", 86400) or 86400),
+            raw=raw,
+        )
+
+    # ── Public matching API ───────────────────────────────────────────
+
+    def match(self, skill: str, tool: str, target: str) -> PatternMatch | None:
+        """Return a PatternMatch if any loaded pattern's action matches.
+
+        Returns None if no pattern's action matches this (skill, tool).
+
+        When a pattern matches, the result indicates whether it is currently
+        armed — i.e., whether rate limit allows it AND circuit breaker is
+        not tripped. The decorator can use armed=True as a hint to skip
+        double-confirm; armed=False means the pattern exists but is rate-limited
+        or in cooldown.
+        """
+        self._maybe_reload()
+
+        # Collect every pattern whose action matches, then prefer the first
+        # ARMABLE one. Previously the first (skill, tool) match won even when
+        # not armable, shadowing a later armable pattern.
+        candidates = [p for p in self._patterns.values() if p.skill == skill and p.tool == tool]
+        if not candidates:
+            return None
+
+        armable = [p for p in candidates if p.is_armable]
+        if not armable:
+            pat = candidates[0]
+            return PatternMatch(
+                pattern=pat,
+                armed=False,
+                reason=f"pattern {pat.pattern_id} is not armable "
+                f"(risk={pat.risk}, expired={pat.is_expired})",
+            )
+
+        for pat in armable:
+            with self._lock:
+                key = (pat.pattern_id, target or "")
+                ctr = self._counters.setdefault(key, _Counters())
+
+                # Circuit breaker check
+                now = time.time()
+                if now < ctr.disabled_until:
+                    remaining = int(ctr.disabled_until - now)
+                    return PatternMatch(
+                        pattern=pat,
+                        armed=False,
+                        reason=f"pattern {pat.pattern_id} circuit-broken for "
+                        f"~{remaining}s after {ctr.consecutive_failures} failures",
+                    )
+
+                # Rate limit check (sliding 1h and 24h windows)
+                hour_ago = now - 3600
+                day_ago = now - 86400
+                ctr.arm_timestamps = [t for t in ctr.arm_timestamps if t > day_ago]
+                arms_last_hour = sum(1 for t in ctr.arm_timestamps if t > hour_ago)
+                arms_last_day = len(ctr.arm_timestamps)
+
+                if (
+                    pat.rate_max_per_hour_per_target
+                    and arms_last_hour >= pat.rate_max_per_hour_per_target
+                ):
+                    return PatternMatch(
+                        pattern=pat,
+                        armed=False,
+                        reason=f"pattern {pat.pattern_id} hit hourly cap "
+                        f"({pat.rate_max_per_hour_per_target}/h) on target {target!r}",
+                    )
+                if (
+                    pat.rate_max_per_day_per_target
+                    and arms_last_day >= pat.rate_max_per_day_per_target
+                ):
+                    return PatternMatch(
+                        pattern=pat,
+                        armed=False,
+                        reason=f"pattern {pat.pattern_id} hit daily cap "
+                        f"({pat.rate_max_per_day_per_target}/d) on target {target!r}",
+                    )
+
+                # Pattern is armed — record the arming timestamp
+                ctr.arm_timestamps.append(now)
+
+            return PatternMatch(pattern=pat, armed=True, reason=f"pattern {pat.pattern_id} armed")
+
+        return None
+
+    def report_outcome(self, pattern_id: str, target: str, success: bool) -> None:
+        """Update circuit-breaker state after an armed pattern's action ran.
+
+        Called by the decorator's finally block once the underlying tool
+        function returns or raises. Successful runs reset the failure
+        counter; failures increment it and may trip the breaker.
+        """
+        with self._lock:
+            key = (pattern_id, target or "")
+            ctr = self._counters.setdefault(key, _Counters())
+            pat = self._patterns.get(pattern_id)
+            threshold = pat.circuit_threshold if pat else 3
+            disable_for = pat.circuit_disable_seconds if pat else 86400
+
+            if success:
+                ctr.consecutive_failures = 0
+                return
+
+            ctr.consecutive_failures += 1
+            if ctr.consecutive_failures >= threshold:
+                ctr.disabled_until = time.time() + disable_for
+                _log.warning(
+                    "pattern %s circuit-broken on target %r after %d failures — disabled for %ds",
+                    pattern_id,
+                    target,
+                    ctr.consecutive_failures,
+                    disable_for,
+                )
+
+    # ── Introspection / testing helpers ──────────────────────────────
+
+    def loaded_patterns(self) -> list[Pattern]:
+        """Return a snapshot of currently loaded patterns."""
+        return list(self._patterns.values())
+
+    def reset_state(self) -> None:
+        """Clear in-memory counters. Used by tests; not for production paths."""
+        with self._lock:
+            self._counters = {}
+
+
+# ── Singleton ─────────────────────────────────────────────────────────
+
+_engine: PatternEngine | None = None
+_engine_lock = threading.Lock()
+
+
+def get_pattern_engine(patterns_dir: Path | str | None = None) -> PatternEngine:
+    """Return the global PatternEngine singleton."""
+    global _engine
+    if _engine is None:
+        with _engine_lock:
+            if _engine is None:
+                _engine = PatternEngine(patterns_dir)
+    return _engine
+
+
+def reset_pattern_engine() -> None:
+    """Reset the singleton. Tests use this to swap directories cleanly."""
+    global _engine
+    _engine = None

apache_aiops/governance/policy.py

@@ -0,0 +1,67 @@
+"""Risk-tier tagging for the audit trail — NOT authorization.
+
+Whether a read or a write is permitted is deliberately not the skill's decision.
+That belongs to the agent's judgement, or to the permissions of the account the
+tool connects with — give it a read-only role and writes fail at the server, the
+place that actually owns the permission. The skill's job is to run the operation
+accurately and record it, both over MCP and over the CLI; it does not police.
+
+An earlier design put a whole authorization layer here — read-only mode, YAML
+deny rules, a secure-by-default approver gate. All of that is gone: it duplicated
+a decision the agent and the account already own, and every gate was one more way
+for a correct operation to be refused.
+
+What remains is a stateless classifier that maps a tool's declared ``risk_level``
+to a tier name carried into the audit log, so a reviewer can see at a glance that
+a row was, say, a high-risk delete. It gates nothing.
+"""
+
+from __future__ import annotations
+
+import threading
+
+RISK_LEVELS = ("low", "medium", "high", "critical")
+
+# risk_level → audit tier. Purely descriptive: no tier blocks anything, it only
+# labels the audit row. 'confirm' echoes that the CLI double-confirms a medium
+# write; 'review' marks the destructive operations a human is most likely to
+# want to see in the trail.
+_TIER_BY_RISK = {
+    "low": "none",
+    "medium": "confirm",
+    "high": "review",
+    "critical": "review",
+}
+
+
+class PolicyEngine:
+    """Stateless risk-tier classifier.
+
+    Kept as a lock-guarded singleton so the ``reset_policy_engine()`` hook the
+    test fixtures call stays valid, but it holds no rules and denies nothing.
+    """
+
+    def tier_for(self, risk_level: str) -> str:
+        """Return the audit tier name for a declared risk level."""
+        return _TIER_BY_RISK.get(risk_level, "none")
+
+
+_engine: PolicyEngine | None = None
+_engine_lock = threading.Lock()
+
+
+def get_policy_engine() -> PolicyEngine:
+    """Return the global PolicyEngine singleton (lazy, lock-guarded)."""
+    global _engine
+    if _engine is None:
+        with _engine_lock:
+            if _engine is None:
+                _engine = PolicyEngine()
+    return _engine
+
+
+def reset_policy_engine() -> None:
+    """Reset the singleton. Tests use this between cases."""
+    global _engine
+    with _engine_lock:
+        _engine = None

apache_aiops/governance/sanitize.py

@@ -0,0 +1,79 @@
+"""Output hygiene: strip control/format characters and truncate untrusted text.
+
+Defense-in-depth against *encoding-level* tricks: control characters,
+zero-width / bidi format characters, and payload-pushing padding. It does NOT
+neutralize natural-language prompt injection — "ignore previous instructions"
+passes through unchanged; semantic injection resistance must come from the
+consuming agent's own prompt boundaries.
+
+Consolidated from 22 duplicate ``_sanitize()`` implementations across the tool line.
+All skills should import from here instead of defining their own copy.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+# C0 control chars (except tab \x09, LF \x0a, CR \x0d) + C1 control chars
+_CONTROL_CHAR_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]")
+
+
+def sanitize(text: str | None, max_len: int = 500) -> str:
+    """Strip control characters, Unicode format chars, and truncate.
+
+    Removes:
+    - C0/C1 control characters (except newline/tab)
+    - Unicode Format characters (Cf): zero-width spaces, bidi overrides,
+      zero-width joiners — used to smuggle or disguise injected text
+
+    Stripping happens BEFORE truncation so an attacker cannot push the real
+    payload past the cut-off by padding with junk control characters.
+    ``None`` sanitizes to ``""``.
+
+    A truncated result ends in an ellipsis (U+2026) so the cut is visible. This
+    line already treats a silent cut as a defect for lists — a capped page that
+    looks complete gets reported as the whole set — and a capped string is the
+    same failure at a smaller scale: a shortened error message reads as the
+    whole explanation, and its remediation sentence, which comes last, is gone
+    without a trace.
+
+    Args:
+        text: Untrusted text from upstream API or command responses.
+        max_len: Maximum length after truncation. Default 500.
+
+    Returns:
+        Cleaned string, ellipsis-terminated when it had to be cut.
+    """
+    if text is None:
+        return ""
+    stripped = _CONTROL_CHAR_RE.sub("", str(text))
+    cleaned = "".join(c for c in stripped if unicodedata.category(c) != "Cf")
+    if len(cleaned) <= max_len:
+        return cleaned
+    return cleaned[: max(0, max_len - 1)] + "\u2026"
+
+
+def opt_str(value: object | None, max_len: int = 500) -> str | None:
+    """Sanitize a value that may legitimately be absent, preserving that absence.
+
+    Companion to :func:`sanitize`, which folds ``None`` into ``""``. That
+    conflation is invisible downstream: an empty string reads as "the field
+    exists and is empty" when the truth may be "the source never returned this
+    field at all". A consumer — and a smaller local model especially — cannot
+    recover the difference, and tends to invent one.
+
+    So: absence comes back as ``None`` (JSON ``null``), and only genuinely empty
+    values come back as ``""``. Use this for any optional API field; keep
+    :func:`sanitize` for values that are always present.
+
+    Args:
+        value: Raw value straight from an API response, or None when absent.
+        max_len: Maximum length after truncation. Default 500.
+
+    Returns:
+        The sanitized string, or None when the source had no value at all.
+    """
+    if value is None:
+        return None
+    return sanitize(str(value), max_len)