agentmetry 0.4.0__py3-none-any.whl

agentmetry/core/diagnostics/env_file.py

@@ -0,0 +1,45 @@
+"""Read/write orchestrator .env keys without pulling in dotenv."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def read_env_key(path: Path, key: str) -> str:
+    if not path.is_file():
+        return ""
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if "=" in line:
+            k, _, v = line.partition("=")
+            if k.strip() == key:
+                return v.strip().strip('"').strip("'")
+    return ""
+
+
+def upsert_env_key(path: Path, key: str, value: str) -> None:
+    """Set or append key=value in a .env file."""
+    lines: list[str] = []
+    if path.is_file():
+        lines = path.read_text(encoding="utf-8").splitlines()
+    out: list[str] = []
+    found = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("#") or "=" not in stripped:
+            out.append(line)
+            continue
+        k, _, _ = stripped.partition("=")
+        if k.strip() == key:
+            out.append(f"{key}={value}")
+            found = True
+        else:
+            out.append(line)
+    if not found:
+        if out and out[-1].strip():
+            out.append("")
+        out.append(f"{key}={value}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(out) + "\n", encoding="utf-8")

agentmetry/core/drivers/__init__.py

@@ -0,0 +1,4 @@
+"""Driver subsystem — MCP tool servers mounted from vault/.system/drivers.json.
+
+Used by the MCP audit proxy demo and optional background driver mount at startup.
+"""

agentmetry/core/drivers/host.py

@@ -0,0 +1,263 @@
+"""MCP host — mounts driver servers and routes governed tool calls.
+
+Each driver runs inside its own owner task, which enters the stdio/SSE
+context, serves calls, and exits it on shutdown. anyio cancel scopes must be
+entered and exited by the same task, so contexts never cross task boundaries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from agentmetry.core.audit.canonical import normalize_arguments_for_audit
+from agentmetry.core.audit.run_context import audit_payload, record_tool_call
+from agentmetry.core.bus.bus import bus
+from agentmetry.core.bus.events import DRIVER_FAILED, DRIVER_MOUNTED, TOOL_CALLED, TOOL_DENIED
+from agentmetry.core.config import settings
+from agentmetry.core.drivers.permissions import (
+    ToolExecApprovalRequired,
+    ToolPermissionError,
+    check_tool_allowed,
+)
+from agentmetry.core.diagnostics.driver_paths import load_resolved_driver_specs
+from agentmetry.core.drivers.spec import DriverSpec
+
+logger = logging.getLogger(__name__)
+
+_MOUNT_TIMEOUT_S = 45  # npx may download a package on first mount
+
+
+@dataclass
+class ToolMeta:
+    driver: str
+    name: str
+    qualified: str
+    description: str
+    tags: list[str] = field(default_factory=list)
+
+
+@dataclass
+class _Driver:
+    spec: DriverSpec
+    session: Any = None
+    task: asyncio.Task | None = None
+    shutdown: asyncio.Event = field(default_factory=asyncio.Event)
+    state: str = "mounting"  # mounting | mounted | failed | stopped
+    error: str = ""
+    tools: list[ToolMeta] = field(default_factory=list)
+
+
+def default_config_path() -> Path:
+    return Path(settings.vault_path) / ".system" / "drivers.json"
+
+
+class MCPHost:
+    def __init__(self):
+        self._drivers: dict[str, _Driver] = {}
+        self._tools: dict[str, ToolMeta] = {}
+
+    # ------------------------------------------------------------ lifecycle
+
+    async def mount_all(self, config_path: Path | None = None) -> None:
+        for spec in load_resolved_driver_specs(config_path or default_config_path()):
+            await self.mount(spec)
+
+    async def mount(self, spec: DriverSpec) -> bool:
+        """Start a driver's owner task; returns True once it is serving."""
+        driver = _Driver(spec=spec)
+        self._drivers[spec.name] = driver
+        ready: asyncio.Future[bool] = asyncio.get_running_loop().create_future()
+        driver.task = asyncio.create_task(
+            self._driver_task(driver, ready), name=f"driver-{spec.name}"
+        )
+        try:
+            return await asyncio.wait_for(ready, timeout=_MOUNT_TIMEOUT_S)
+        except asyncio.TimeoutError:
+            driver.state = "failed"
+            driver.error = f"mount timed out after {_MOUNT_TIMEOUT_S}s"
+            driver.shutdown.set()
+            logger.warning("Driver %s: %s", spec.name, driver.error)
+            return False
+
+    async def _driver_task(self, driver: _Driver, ready: asyncio.Future) -> None:
+        spec = driver.spec
+        try:
+            if spec.transport == "stdio":
+                from mcp import ClientSession, StdioServerParameters
+                from mcp.client.stdio import stdio_client
+
+                params = StdioServerParameters(
+                    command=spec.command, args=spec.args, env=spec.build_env()
+                )
+                async with stdio_client(params) as (read, write):
+                    async with ClientSession(read, write) as session:
+                        await self._serve(driver, session, ready)
+            elif spec.transport == "sse":
+                from mcp import ClientSession
+                from mcp.client.sse import sse_client
+
+                async with sse_client(spec.url) as (read, write):
+                    async with ClientSession(read, write) as session:
+                        await self._serve(driver, session, ready)
+            else:
+                raise ValueError(f"Unknown transport '{spec.transport}'")
+        except Exception as exc:
+            driver.state = "failed"
+            driver.error = str(exc)[:200]
+            logger.warning("Driver %s failed: %s", spec.name, driver.error)
+            bus.publish(DRIVER_FAILED, {
+                "type": "driver_failed",
+                "driver": spec.name,
+                "error": driver.error,
+            })
+        finally:
+            self._deregister(spec.name)
+            driver.session = None
+            if driver.state != "failed":
+                driver.state = "stopped"
+            if not ready.done():
+                ready.set_result(False)
+
+    async def _serve(self, driver: _Driver, session: Any, ready: asyncio.Future) -> None:
+        spec = driver.spec
+        await session.initialize()
+        listed = await session.list_tools()
+        driver.tools = [
+            ToolMeta(
+                driver=spec.name,
+                name=tool.name,
+                qualified=f"{spec.name}.{tool.name}",
+                description=tool.description or "",
+                tags=list(spec.tags),
+            )
+            for tool in listed.tools
+        ]
+        for meta in driver.tools:
+            self._tools[meta.qualified] = meta
+        driver.session = session
+        driver.state = "mounted"
+        logger.info("Driver %s mounted: %d tool(s)", spec.name, len(driver.tools))
+        bus.publish(DRIVER_MOUNTED, {
+            "type": "driver_mounted",
+            "driver": spec.name,
+            "tools": [m.qualified for m in driver.tools],
+        })
+        if not ready.done():
+            ready.set_result(True)
+        await driver.shutdown.wait()
+
+    async def unmount_all(self) -> None:
+        for driver in self._drivers.values():
+            driver.shutdown.set()
+        for driver in self._drivers.values():
+            if driver.task:
+                try:
+                    await asyncio.wait_for(driver.task, timeout=10)
+                except (asyncio.TimeoutError, asyncio.CancelledError):
+                    driver.task.cancel()
+        self._drivers.clear()
+        self._tools.clear()
+
+    def _deregister(self, driver_name: str) -> None:
+        self._tools = {
+            q: m for q, m in self._tools.items() if m.driver != driver_name
+        }
+
+    # ------------------------------------------------------------ inspection
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            name: {
+                "state": d.state,
+                "transport": d.spec.transport,
+                "tags": d.spec.tags,
+                "tools": len(d.tools),
+                **({"error": d.error} if d.error else {}),
+            }
+            for name, d in self._drivers.items()
+        }
+
+    def list_tools(self) -> list[dict[str, Any]]:
+        return [
+            {
+                "qualified": m.qualified,
+                "driver": m.driver,
+                "description": m.description,
+                "tags": m.tags,
+            }
+            for m in self._tools.values()
+        ]
+
+    # ------------------------------------------------------------ execution
+
+    async def call_tool(
+        self,
+        qualified: str,
+        arguments: dict[str, Any],
+        *,
+        skill_config: dict[str, Any],
+        session_id: str = "",
+        thread_id: str = "",
+    ) -> Any:
+        """Governed tool call: allowlist + Tier 0 exec gate + audit events."""
+        meta = self._tools.get(qualified)
+        if meta is None:
+            raise ToolPermissionError(f"No such tool mounted: '{qualified}'")
+
+        skill_name = skill_config.get("name", "?")
+        try:
+            check_tool_allowed(skill_config, qualified, tags=meta.tags)
+        except ToolExecApprovalRequired:
+
+            bus.publish(TOOL_DENIED, {
+                "type": "tool_denied",
+                "tool": qualified,
+                "skill": skill_name,
+                "reason": "tool_exec_approval",
+                "arguments_sha256": normalize_arguments_for_audit(arguments),
+                **audit_payload(thread_id),
+            }, session_id=session_id, thread_id=thread_id)
+            raise
+        except Exception:
+            bus.publish(TOOL_DENIED, {
+                "type": "tool_denied",
+                "tool": qualified,
+                "skill": skill_name,
+                "reason": "not_allowed",
+                "arguments_sha256": normalize_arguments_for_audit(arguments),
+                **audit_payload(thread_id),
+            }, session_id=session_id, thread_id=thread_id)
+            raise
+
+        driver = self._drivers.get(meta.driver)
+        if driver is None or driver.state != "mounted" or driver.session is None:
+            raise RuntimeError(f"Driver '{meta.driver}' is not mounted")
+
+        result = await driver.session.call_tool(meta.name, arguments)
+        args_hash = normalize_arguments_for_audit(arguments)
+        record_tool_call(thread_id, qualified, args_hash)
+        payload: dict[str, Any] = {
+            "type": "tool_called",
+            "tool": qualified,
+            "skill": skill_name,
+            "arguments_sha256": args_hash,
+            **audit_payload(thread_id),
+        }
+        if qualified == "gmail.send_draft":
+            payload["draft_id"] = arguments.get("draft_id")
+        bus.publish(TOOL_CALLED, payload, session_id=session_id, thread_id=thread_id)
+        return result
+
+
+_host: MCPHost | None = None
+
+
+def get_mcp_host() -> MCPHost:
+    global _host
+    if _host is None:
+        _host = MCPHost()
+    return _host

agentmetry/core/drivers/permissions.py

@@ -0,0 +1,37 @@
+"""Tool permissions — closed by default, per-skill allowlists, Tier 0 exec gate."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatch
+from typing import Any
+
+
+class ToolPermissionError(Exception):
+    """The skill's YAML does not allow this tool."""
+
+
+class ToolExecApprovalRequired(ToolPermissionError):
+    """Tier 0 sandbox policy: exec-tagged tools are denied until a sandbox
+    tier exists; each denial is recorded as a TOOL_EXEC_APPROVAL interrupt."""
+
+
+def check_tool_allowed(
+    skill_config: dict[str, Any],
+    qualified: str,
+    *,
+    tags: list[str],
+) -> None:
+    """Raise unless the skill's `tools:` allowlist covers this qualified name.
+
+    Closed by default: a skill without a `tools:` key can call nothing.
+    Patterns use fnmatch, e.g. ["fs.read_file", "search.*"].
+    """
+    allow = skill_config.get("tools") or []
+    if not any(fnmatch(qualified, pattern) for pattern in allow):
+        raise ToolPermissionError(
+            f"Skill '{skill_config.get('name', '?')}' does not allow tool '{qualified}'"
+        )
+    if "exec" in tags:
+        raise ToolExecApprovalRequired(
+            f"Tool '{qualified}' is exec-tagged — denied by Tier 0 sandbox policy"
+        )

agentmetry/core/drivers/spec.py

@@ -0,0 +1,118 @@
+"""Driver specs — operator-owned config, resilient loading, scrubbed env."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+
+from pydantic import BaseModel, Field, ValidationError
+
+logger = logging.getLogger(__name__)
+
+# Minimum a Windows subprocess needs to start node/python at all. Secrets like
+# GEMINI_API_KEY never cross into a driver unless env_allow names them.
+_BASE_ENV_NAMES = (
+    "SYSTEMROOT",
+    "PATH",
+    "PATHEXT",
+    "COMSPEC",
+    "TEMP",
+    "TMP",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "USERPROFILE",
+    "PROGRAMFILES",
+    "HOME",
+)
+
+
+def _orchestrator_env_file() -> Path:
+    return Path(__file__).resolve().parents[3] / ".env"
+
+
+def _dotenv_values() -> dict[str, str]:
+    """Minimal KEY=VALUE parse of the orchestrator .env (gitignored secrets).
+
+    pydantic-settings reads .env into Settings fields only — it never exports
+    to os.environ — so env_allow names documented as ".env keys" (SERPER,
+    GMAIL client creds, ...) would otherwise silently never reach a driver.
+    """
+    path = _orchestrator_env_file()
+    if not path.exists():
+        return {}
+    values: dict[str, str] = {}
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            key, _, value = line.partition("=")
+            values[key.strip()] = value.strip().strip('"').strip("'")
+    except OSError as exc:
+        logger.warning("Could not read %s for driver env: %s", path, exc)
+    return values
+
+
+def base_subprocess_env(extra_names: list[str] | None = None) -> dict[str, str]:
+    """Allowlist-only environment for any sandboxed/driver subprocess.
+
+    Allowlisted names resolve from the live process env first, then fall back
+    to the orchestrator's .env file. Base names never fall back — they are
+    OS plumbing, not secrets.
+    """
+    result: dict[str, str] = {}
+    for name in _BASE_ENV_NAMES:
+        value = os.environ.get(name)
+        if value is not None:
+            result[name] = value
+    if extra_names:
+        dotenv = _dotenv_values()
+        for name in extra_names:
+            value = os.environ.get(name, dotenv.get(name))
+            if value is not None:
+                result[name] = value
+    return result
+
+
+class DriverSpec(BaseModel):
+    name: str = Field(pattern=r"^[a-z0-9_-]+$")
+    transport: str = "stdio"  # stdio | sse
+    command: str = ""
+    args: list[str] = Field(default_factory=list)
+    url: str = ""
+    env: dict[str, str] = Field(default_factory=dict)
+    env_allow: list[str] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)
+    enabled: bool = True
+
+    def build_env(self) -> dict[str, str]:
+        """Allowlist-only environment for the driver subprocess."""
+        result = base_subprocess_env(self.env_allow)
+        result.update(self.env)
+        return result
+
+
+def load_driver_specs(config_path: Path) -> list[DriverSpec]:
+    """Read drivers.json; a malformed entry never blocks the others."""
+    if not config_path.exists():
+        return []
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        logger.warning("drivers.json unreadable (%s) — no drivers mounted", exc)
+        return []
+
+    specs: list[DriverSpec] = []
+    for entry in data.get("drivers", []):
+        try:
+            spec = DriverSpec.model_validate(entry)
+        except ValidationError as exc:
+            logger.warning("Skipping invalid driver entry %r: %s", entry.get("name"), exc)
+            continue
+        if not spec.enabled:
+            logger.info("Driver %s is disabled — skipped", spec.name)
+            continue
+        specs.append(spec)
+    return specs

agentmetry/core/extensions.py

@@ -0,0 +1,107 @@
+"""Optional extension loader for enterprise add-ons.
+
+Third-party packages register via setuptools entry points in the group
+``agentmetry.extensions``::
+
+    [project.entry-points."agentmetry.extensions"]
+    enterprise = "agentmetry_enterprise.register:register"
+
+The orchestrator discovers installed extensions at startup and calls
+``register(app, settings=...)``. When no enterprise package is installed,
+this module is a no-op and the OSS quickstart is unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from importlib.metadata import entry_points, version
+from typing import Any, Protocol, runtime_checkable
+
+from fastapi import FastAPI
+
+logger = logging.getLogger(__name__)
+
+EXTENSION_GROUP = "agentmetry.extensions"
+
+
+@runtime_checkable
+class AgentmetryExtension(Protocol):
+    """Contract for ``agentmetry.extensions`` entry points."""
+
+    def register(self, app: FastAPI, *, settings: Any) -> None: ...
+
+
+@dataclass
+class ExtensionInfo:
+    name: str
+    value: str
+    distribution: str | None = None
+
+
+@dataclass
+class ExtensionRegistry:
+    loaded: list[ExtensionInfo] = field(default_factory=list)
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "count": len(self.loaded),
+            "extensions": [
+                {
+                    "name": item.name,
+                    "entry": item.value,
+                    "distribution": item.distribution,
+                }
+                for item in self.loaded
+            ],
+        }
+
+
+_registry = ExtensionRegistry()
+
+
+def get_extension_registry() -> ExtensionRegistry:
+    return _registry
+
+
+def _iter_extension_entry_points():
+    try:
+        return entry_points(group=EXTENSION_GROUP)
+    except TypeError:
+        return entry_points().select(group=EXTENSION_GROUP)
+
+
+def _distribution_for_module(module_name: str) -> str | None:
+    root = module_name.split(".", 1)[0]
+    try:
+        return version(root)
+    except Exception:
+        return None
+
+
+def load_extensions(app: FastAPI, *, settings: Any) -> ExtensionRegistry:
+    """Discover and invoke all ``agentmetry.extensions`` entry points."""
+    _registry.loaded.clear()
+
+    for ep in sorted(_iter_extension_entry_points(), key=lambda e: e.name):
+        try:
+            target = ep.load()
+            if not callable(target):
+                raise TypeError(f"entry point {ep.value!r} is not callable")
+            target(app, settings=settings)
+            module = ep.module or ep.value.split(":", 1)[0]
+            _registry.loaded.append(
+                ExtensionInfo(
+                    name=ep.name,
+                    value=ep.value,
+                    distribution=_distribution_for_module(module),
+                )
+            )
+            logger.info("Loaded Agentmetry extension %r (%s)", ep.name, ep.value)
+        except Exception:
+            logger.exception("Failed to load Agentmetry extension %r (%s)", ep.name, ep.value)
+
+    if not _registry.loaded:
+        logger.debug("No Agentmetry extensions installed (group=%s)", EXTENSION_GROUP)
+
+    return _registry

agentmetry/core/health.py

@@ -0,0 +1,26 @@
+"""Service health for Agentmetry SIEM."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentmetry.core.config import settings
+from agentmetry.core.extensions import get_extension_registry
+from pathlib import Path
+
+
+async def get_system_health() -> dict[str, Any]:
+    """Return health of the SIEM components."""
+    path = Path(settings.audit_export_path)
+    extensions = get_extension_registry().summary()
+
+    return {
+        "status": "up",
+        "mode": "siem",
+        "audit_export": {
+            "enabled": settings.audit_export_enabled,
+            "path": str(path),
+            "accessible": path.parent.exists() if settings.audit_export_enabled else None,
+        },
+        "extensions": extensions,
+    }

agentmetry/core/version.py

@@ -0,0 +1,13 @@
+"""Single source of truth for the Agentmetry version.
+
+`pyproject.toml` reads this file (hatchling `[tool.hatch.version]`), the API
+advertises it, and `tests/test_version.py` asserts it matches the newest
+released CHANGELOG entry. Evidence packs record the producing version, so a
+version that disagrees with the tag is a provenance defect, not cosmetics.
+
+Bump this here and add the matching CHANGELOG section in the same commit.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.4.0"

agentmetry/policies/detection/manifest.yaml

@@ -0,0 +1,43 @@
+version: "1.0"
+
+# Tunable thresholds for built-in sequence rules (hot-reload on orchestrator restart).
+thresholds:
+  discovery_burst: 3
+  delete_burst: 5
+  subagent_burst: 5
+  session_tool_burst: 40
+  host_subagent_burst: 8
+
+  # Burst rules need a clock as well as a count: N events must land inside the
+  # window to fire. Without one, 40 tool calls is just a long coding session and
+  # 8 subagent starts is two quiet weeks — both used to alert as "autonomous
+  # campaign". Set a window to 0 to match on the raw count instead.
+  subagent_burst_window_minutes: 15
+  session_tool_burst_window_minutes: 10
+  host_subagent_burst_window_minutes: 60
+
+# Analyst-authored count rules — no Python PR required. Fires when ≥ min_count
+# events in one session match all filters in `match`.
+count_rules:
+  - id: rapid-tool-denials
+    title: Rapid tool denials in one session
+    severity: medium
+    summary: "{count} denied tool calls — possible policy probing or injection retries"
+    tactic_ids: ["TA0005"]
+    technique_ids: ["T1562"]
+    min_count: 5
+    match:
+      action_type: tool_called
+      outcome: denied
+
+  - id: rapid-dlp-blocks
+    title: Repeated DLP blocks in one session
+    severity: high
+    summary: "{count} DLP-related denials — secrets may be present in agent context"
+    tactic_ids: ["TA0010"]
+    technique_ids: ["T1552"]
+    min_count: 3
+    match:
+      action_type: tool_called
+      outcome: denied
+      reason_prefix: "dlp:"