mayhem-cli 0.5.1__py3-none-any.whl

mayhem/toolkit/fingerprint.py

@@ -0,0 +1,69 @@
+"""Environment fingerprinting — the 'same environment' predicate (run contract).
+
+A run's ``environment_fingerprint`` must change whenever anything that could
+alter fault outcomes changes: OS, arch, python, controller version, or the
+version/output of any chaos backend present on the host.
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+from typing import Any
+
+from mayhem.toolkit.hashing import digest
+from mayhem.toolkit.tool_runner import ToolResult, run_tool
+
+CONTROLLER_VERSION = "0.1.0"
+
+_PROBED_TOOLS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    ("docker", ("docker", "--version")),
+    ("kubectl", ("kubectl", "version", "--client=true", "-o", "json")),
+    ("tc", ("tc", "-Version")),
+    ("iptables", ("iptables", "--version")),
+    ("stress-ng", ("stress-ng", "--version")),
+)
+
+
+def build_fingerprint(tool_versions: dict[str, str | None]) -> str:
+    """Pure hash over the environment descriptor."""
+    descriptor: dict[str, Any] = {
+        "controller_version": CONTROLLER_VERSION,
+        "os": platform.system(),
+        "os_release": platform.release(),
+        "arch": platform.machine(),
+        "python": platform.python_version(),
+        "tools": dict(sorted(tool_versions.items())),
+    }
+    return digest(descriptor)
+
+
+def collect_tool_versions(
+    probed: tuple[tuple[str, tuple[str, ...]], ...] = _PROBED_TOOLS,
+) -> tuple[dict[str, str | None], list[ToolResult]]:
+    """Probe known backends; missing tools are recorded as None, never fatal."""
+    versions: dict[str, str | None] = {}
+    evidence: list[ToolResult] = []
+    for name, argv in probed:
+        try:
+            result = run_tool(argv, timeout_s=10)
+        except Exception:  # a missing tool is an expected outcome
+            versions[name] = None
+            continue
+        if result.succeeded or result.exit_code is not None:
+            first_line = result.stdout.strip().splitlines()
+            versions[name] = first_line[0][:200] if first_line else result.stderr[:200]
+        else:
+            versions[name] = None
+        evidence.append(result)
+    return versions, evidence
+
+
+def current_fingerprint() -> str:
+    versions, _ = collect_tool_versions()
+    return build_fingerprint(versions)
+
+
+def interpreter_marker() -> str:
+    """Cheap identity of this python process; used by agent heartbeats."""
+    return f"python-{sys.version_info.major}.{sys.version_info.minor}"

mayhem/toolkit/hashing.py

@@ -0,0 +1,32 @@
+"""Canonical hashing helpers — one definition of 'same input' for the whole system."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def canonical_json(value: Any) -> str:
+    """Deterministic JSON encoding: sorted keys, no whitespace, stable unicode."""
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        default=str,
+    )
+
+
+def sha256_hex(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def digest(value: Any) -> str:
+    """Hash any JSON-compatible value canonically."""
+    return sha256_hex(canonical_json(value))
+
+
+def digest_mapping(mapping: dict[str, Any]) -> str:
+    """Hash a mapping by its canonical form."""
+    return digest(dict(mapping))

mayhem/toolkit/manifests/docker.yaml

@@ -0,0 +1,11 @@
+tool: docker
+provides: [container.kill, container.pause, container.exec]
+probe:
+  cmd: [docker, --version]
+  version_regex: 'Docker version (?P<v>[\d.]+)'
+privilege: sudo_patterns
+risk: high
+fallback_groups:
+  container.kill: fallback_1
+  container.pause: fallback_1
+  container.exec: primary

mayhem/toolkit/manifests/podman.yaml

@@ -0,0 +1,11 @@
+tool: podman
+provides: [container.kill, container.pause, container.exec]
+probe:
+  cmd: [podman, --version]
+  version_regex: 'podman version (?P<v>[\d.]+)'
+privilege: none
+risk: high
+fallback_groups:
+  container.kill: primary
+  container.pause: primary
+  container.exec: fallback_1

mayhem/toolkit/manifests/stress-ng.yaml

@@ -0,0 +1,11 @@
+tool: stress-ng
+provides: [cpu.pressure, mem.pressure, io.stress]
+probe:
+  cmd: [stress-ng, --version]
+  version_regex: 'version\s+(?P<v>[\d.]+)'
+privilege: none
+risk: medium
+fallback_groups:
+  cpu.pressure: primary
+  mem.pressure: primary
+  io.stress: primary

mayhem/toolkit/manifests/tc-netem.yaml

@@ -0,0 +1,11 @@
+tool: tc
+provides: [net.latency, net.loss, net.partition]
+probe:
+  cmd: [tc, -Version]
+  version_regex: 'tc utility, iproute2-(?P<v>[\w.\-]+)'
+privilege: root
+risk: high
+fallback_groups:
+  net.latency: primary
+  net.loss: primary
+  net.partition: fallback_1

mayhem/toolkit/manifests/toxiproxy.yaml

@@ -0,0 +1,10 @@
+tool: toxiproxy
+provides: [net.latency, net.partition]
+probe:
+  cmd: [toxiproxy-cli, --version]
+  version_regex: '(?P<v>\d+\.\d+\.\d+)'
+privilege: none
+risk: medium
+fallback_groups:
+  net.latency: fallback_1
+  net.partition: primary

mayhem/toolkit/registry.py

@@ -0,0 +1,185 @@
+"""Capability registry — declarative manifests + probing + fallback chains.
+
+ADR-0004: every external tool is declared as data (a manifest), probed once at
+handshake, and resolved per capability through an ordered fallback chain.
+ADR-0011: this registry *is* the extension point — new tool = new manifest +
+adapter; agents never hardcode binaries.
+"""
+
+from __future__ import annotations
+
+import re
+from enum import StrEnum
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+from mayhem.domain.errors import SchemaValidationError
+from mayhem.domain.risks import RiskLevel
+from mayhem.toolkit.tool_runner import run_tool
+
+BUILTIN_MANIFESTS_DIR = Path(__file__).parent / "manifests"
+
+
+class Privilege(StrEnum):
+    NONE = "none"
+    SUDO_PATTERNS = "sudo_patterns"
+    ROOT = "root"
+
+
+_FALLBACK_NAME = re.compile(r"^(primary|fallback_(?P<n>[1-9]\d*))$")
+
+
+def _fallback_rank(name: str) -> int:
+    if name == "primary":
+        return 0
+    match = _FALLBACK_NAME.match(name)
+    if match is None:
+        raise SchemaValidationError(
+            "fallback_rank", f"invalid slot name {name!r} (primary|fallback_N)"
+        )
+    return int(match.group("n"))
+
+
+class CapabilityManifest(BaseModel):
+    """One external tool, declared as data."""
+
+    model_config = ConfigDict(frozen=True)
+
+    tool: str
+    provides: tuple[str, ...]
+    probe_cmd: tuple[str, ...]
+    version_regex: str
+    privilege: Privilege = Privilege.NONE
+    risk: RiskLevel = RiskLevel.MEDIUM
+    fallback_slots: dict[str, str] = Field(default_factory=dict)  # capability → primary|fallback_N
+
+    @field_validator("provides")
+    @classmethod
+    def _nonempty(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if not value:
+            raise SchemaValidationError("manifest", "tool must provide ≥1 capability")
+        return value
+
+    @field_validator("probe_cmd")
+    @classmethod
+    def _argv_only(cls, value: tuple[str, ...]) -> tuple[str, ...]:
+        if not value or any(not part for part in value):
+            raise SchemaValidationError("manifest", "probe_cmd must be a non-empty argv list")
+        return value
+
+    @field_validator("fallback_slots")
+    @classmethod
+    def _slots_reference_provided(
+        cls, value: dict[str, str], info: ValidationInfo
+    ) -> dict[str, str]:
+        provides = info.data.get("provides", ())
+        for capability, slot in value.items():
+            if capability not in provides:
+                raise SchemaValidationError(
+                    "fallback_rank",
+                    f"slot for {capability!r} but tool does not provide it",
+                )
+            _fallback_rank(slot)  # validates name shape
+        return value
+
+    def rank_for(self, capability: str) -> int | None:
+        slot = self.fallback_slots.get(capability)
+        return None if slot is None else _fallback_rank(slot)
+
+
+class ProbedTool(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    manifest: CapabilityManifest
+    version: str
+
+
+class CapabilityReport(BaseModel):
+    """Cached probe outcome per host. Refreshed explicitly, never mid-run."""
+
+    model_config = ConfigDict(frozen=True)
+
+    host: str
+    tools: tuple[ProbedTool, ...] = ()
+
+    def has(self, capability_id: str) -> bool:
+        return any(capability_id in t.manifest.provides for t in self.tools)
+
+
+class ToolRegistry:
+    """Registry of manifests + cached probes + ranked fallback resolution."""
+
+    def __init__(self, manifests: tuple[CapabilityManifest, ...] = ()) -> None:
+        self._manifests: dict[str, CapabilityManifest] = {}
+        self._reports: dict[str, CapabilityReport] = {}
+        for manifest in manifests:
+            self.register(manifest)
+
+    def register(self, manifest: CapabilityManifest) -> None:
+        if manifest.tool in self._manifests:
+            raise SchemaValidationError("registry", f"duplicate tool manifest: {manifest.tool}")
+        self._manifests[manifest.tool] = manifest
+        self._reports.clear()  # new tool may satisfy capabilities on known hosts
+
+    @property
+    def manifests(self) -> tuple[CapabilityManifest, ...]:
+        return tuple(self._manifests.values())
+
+    def probe(self, host: str = "local") -> CapabilityReport:
+        """Run each manifest's probe_cmd; keep only tools that answer with a version."""
+        probed: list[ProbedTool] = []
+        for manifest in sorted(self._manifests.values(), key=lambda m: m.tool):
+            try:
+                result = run_tool(list(manifest.probe_cmd), timeout_s=10.0)
+            except Exception:
+                continue  # binary missing / not executable → simply not capable here
+            match = re.search(manifest.version_regex, result.stdout + result.stderr)
+            if result.succeeded and match:
+                probed.append(ProbedTool(manifest=manifest, version=match.group("v")))
+        report = CapabilityReport(host=host, tools=tuple(probed))
+        self._reports[host] = report
+        return report
+
+    def report_for(self, host: str = "local") -> CapabilityReport:
+        return self._reports.get(host) or self.probe(host)
+
+    def refresh(self, host: str = "local") -> CapabilityReport:
+        """Explicit re-probe; never called implicitly mid-run."""
+        return self.probe(host)
+
+    def resolve(self, capability_id: str, host: str = "local") -> tuple[CapabilityManifest, ...]:
+        """Ranked candidates for a capability, filtered by the host's cached probe."""
+        candidates: list[tuple[int, CapabilityManifest]] = []
+        for probed in self.report_for(host).tools:
+            manifest = probed.manifest
+            if capability_id not in manifest.provides:
+                continue
+            rank = manifest.rank_for(capability_id)
+            candidates.append((rank if rank is not None else 10**6, manifest))
+        candidates.sort(key=lambda pair: pair[0])
+        return tuple(m for _, m in candidates)
+
+
+def manifest_from_yaml(path: Path) -> CapabilityManifest:
+    raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    slots_raw = raw.pop("fallback_groups", {}) or {}
+    slots = {capability: slot for capability, slot in slots_raw.items() if slot is not None}
+    return CapabilityManifest(
+        tool=raw["tool"],
+        provides=tuple(raw["provides"]),
+        probe_cmd=tuple(raw["probe"]["cmd"]),
+        version_regex=raw["probe"]["version_regex"],
+        privilege=Privilege(raw.get("privilege", "none")),
+        risk=RiskLevel(raw.get("risk", "medium")),
+        fallback_slots=slots,
+    )
+
+
+def default_registry() -> ToolRegistry:
+    registry = ToolRegistry()
+    if BUILTIN_MANIFESTS_DIR.is_dir():
+        for path in sorted(BUILTIN_MANIFESTS_DIR.glob("*.yaml")):
+            registry.register(manifest_from_yaml(path))
+    return registry

mayhem/toolkit/tool_runner.py

@@ -0,0 +1,129 @@
+"""Tool execution with full evidence capture (tool-run contract).
+
+Every external invocation goes through ``run_tool`` so the run record can
+reconstruct: exact argv, environment digest, host, exit code, duration, and
+(truncation-bounded) output. Nothing else in the codebase may spawn processes.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from mayhem.domain.errors import DomainError
+from mayhem.toolkit.hashing import digest_mapping
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+DEFAULT_MAX_OUTPUT_BYTES = 1_048_576  # 1 MiB per stream
+
+
+class ToolError(DomainError):
+    """A tool invocation could not be executed at all."""
+
+
+class ToolTimeoutError(ToolError):
+    """The tool exceeded its time budget and was killed."""
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    argv: tuple[str, ...]
+    argv_digest: str
+    env_digest: str
+    host: str
+    cwd: str | None
+    exit_code: int | None
+    duration_ms: int
+    stdout: str
+    stderr: str
+    truncated: bool
+
+    @property
+    def succeeded(self) -> bool:
+        return self.exit_code == 0
+
+    def to_row(self, *, invocation_ref: str | None = None) -> dict[str, Any]:
+        """Shape matching the tool_runs table (stdout/stderr refs added by caller)."""
+        return {
+            "id": self.argv_digest,
+            "invocation_ref": invocation_ref,
+            "argv_digest": self.argv_digest,
+            "argv_json": list(self.argv),
+            "env_digest": self.env_digest,
+            "host": self.host,
+            "exit_code": self.exit_code,
+            "duration_ms": self.duration_ms,
+            "truncated": int(self.truncated),
+            "stdout_ref": None,
+            "stderr_ref": None,
+        }
+
+
+def _truncate(data: bytes, limit: int) -> tuple[str, bool]:
+    truncated = len(data) > limit
+    text = data[:limit].decode("utf-8", errors="replace")
+    if truncated:
+        text += "\n...[TRUNCATED]"
+    return text, truncated
+
+
+def run_tool(
+    argv: list[str] | tuple[str, ...],
+    *,
+    env: dict[str, str] | None = None,
+    cwd: Path | str | None = None,
+    timeout_s: float | None = None,
+    max_output_bytes: int = DEFAULT_MAX_OUTPUT_BYTES,
+    stdin_data: str | None = None,
+) -> ToolResult:
+    """Run a tool synchronously; never raises for non-zero exit codes.
+
+    Raises ToolError only when the process could not be started or timed out —
+    those are harness failures, not tool failures, and callers must record them.
+    """
+    argv_tuple = tuple(argv)
+    if not argv_tuple:
+        raise ToolError("tool_runner", "refusing to execute empty argv")
+    effective_env = dict(env) if env is not None else dict(os.environ)
+    started = time.monotonic()
+    try:
+        completed = subprocess.run(
+            argv_tuple,
+            capture_output=True,
+            text=False,
+            env=effective_env,
+            cwd=str(cwd) if cwd else None,
+            timeout=timeout_s,
+            input=stdin_data.encode("utf-8") if stdin_data is not None else b"",
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise ToolTimeoutError(
+            "tool_runner",
+            f"{argv_tuple[0]} exceeded timeout of {timeout_s}s",
+        ) from exc
+    except OSError as exc:
+        raise ToolError("tool_runner", f"failed to start {argv_tuple[0]}: {exc}") from exc
+    duration_ms = int((time.monotonic() - started) * 1000)
+
+    stdout_text, stdout_truncated = _truncate(completed.stdout or b"", max_output_bytes)
+    stderr_text, stderr_truncated = _truncate(completed.stderr or b"", max_output_bytes)
+
+    return ToolResult(
+        argv=argv_tuple,
+        argv_digest=digest_mapping({"argv": list(argv_tuple)}),
+        env_digest=digest_mapping(effective_env),
+        host=platform.node(),
+        cwd=str(cwd) if cwd else None,
+        exit_code=completed.returncode,
+        duration_ms=duration_ms,
+        stdout=stdout_text,
+        stderr=stderr_text,
+        truncated=stdout_truncated or stderr_truncated,
+    )

mayhem/topology/__init__.py

@@ -0,0 +1,10 @@
+"""Topology discovery pipeline (ADR-0006, ADR-0013).
+
+Providers produce :class:`PartialGraph` fragments; the TopologyService merges
+blueprint (compose) with live truth (container engines / host processes) and
+emits a drift report.
+"""
+
+from mayhem.topology.service import DiscoveryResult, TopologyService
+
+__all__ = ["DiscoveryResult", "TopologyService"]

mayhem/topology/providers/adapter_registry.py

@@ -0,0 +1,60 @@
+"""Adapter registry — lookup and instantiate RuntimeAdapter by engine name.
+
+``best_effort(engine)`` returns the first available adapter, preferring
+Docker when *engine* is None (preserving existing semantics from
+``ContainerRuntimeProvider.best_effort``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mayhem.domain.runtime_adapter import RuntimeAdapter
+
+_REGISTRY: dict[str, type[RuntimeAdapter]] = {}
+
+
+def register(name: str, cls: type[RuntimeAdapter]) -> None:
+    """Register an adapter class under *name*."""
+    _REGISTRY[name] = cls
+
+
+def best_effort(engine: str | None = None) -> RuntimeAdapter | None:
+    """Return an adapter for *engine*, or the first available one.
+
+    When *engine* is None the lookup order is ``["docker", "podman"]``
+    so Docker is preferred, matching the prior
+    ``ContainerRuntimeProvider.best_effort`` behaviour.
+    """
+    if engine is not None:
+        cls = _REGISTRY.get(engine)
+        if cls is not None:
+            adapter = cls(engine)  # type: ignore[call-arg]
+            if adapter.is_available():
+                return adapter
+        return None
+
+    for candidate in ("docker", "podman"):
+        cls = _REGISTRY.get(candidate)
+        if cls is not None:
+            adapter = cls()
+            if adapter.is_available():
+                return adapter
+    return None
+
+
+# Auto-register on import.
+from mayhem.topology.providers.docker_adapter import DockerAdapter  # noqa: E402
+from mayhem.topology.providers.podman_adapter import PodmanAdapter  # noqa: E402
+
+register("docker", DockerAdapter)
+register("podman", PodmanAdapter)
+
+# ── Kubernetes adapter (ADR-M7-1) ───────────────────────────────────────────
+# Registered so ``best_effort("kubernetes")`` can locate the contract.
+# ``KubernetesAdapter.is_available()`` always returns ``False``; the adapter
+# is purely interface-level until a live-cluster driver ships (M8).
+from mayhem.domain.k8s_adapter import KubernetesAdapter  # noqa: E402
+
+register("kubernetes", KubernetesAdapter)

mayhem/topology/providers/base.py

@@ -0,0 +1,31 @@
+"""Provider seam: every discovery source implements :class:`TopologyProvider`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from mayhem.domain.topology import Edge, TopologyNode
+
+
+@dataclass(frozen=True)
+class PartialGraph:
+    """One provider's fragment of the world; merged by the TopologyService."""
+
+    source: str  # provider id, e.g. "compose", "docker", "podman", "host"
+    nodes: tuple[TopologyNode, ...] = ()
+    edges: tuple[Edge, ...] = ()
+    notes: tuple[str, ...] = field(default_factory=tuple)  # provider-level caveats
+
+
+@runtime_checkable
+class TopologyProvider(Protocol):
+    """``async discover()`` is the contract (ADR-0006); sync MVP uses discover_sync."""
+
+    @property
+    def id(self) -> str: ...
+
+    def is_available(self) -> bool: ...
+
+    def discover(self) -> PartialGraph: ...