agentmetry 0.9.0__tar.gz → 0.9.2__tar.gz

{agentmetry-0.9.0 → agentmetry-0.9.2}/.env.example

@@ -5,7 +5,10 @@
 # Demo MCP vault path (relative to this directory)
 AGENTMETRY_VAULT_PATH=../../vault
 
-AGENTMETRY_OPERATOR_ID=local
+# Who ran the agent. Leave empty and every event records the OS account the
+# agent ran as (DOMAIN\user on a domain or Entra Windows account). Set it to
+# override: an email, or a pseudonym to keep account names out of a SIEM.
+AGENTMETRY_OPERATOR_ID=
 AGENTMETRY_FLEET_ID=
 AGENTMETRY_API_KEY=
 
@@ -24,4 +27,9 @@ AGENTMETRY_AUDIT_SINK=file
 # host. See docs/anchoring.md.
 # AGENTMETRY_ANCHOR_LOG=../agentmetry-anchors/home-lab/agentmetry-trail.anchors.jsonl
 
+# The configured MCP servers as an `mcp_inventory` event, for a fleet that wants
+# them in the SIEM: names, launchers, package names and hosts, never arguments or
+# env values. Off by default, because the heartbeat names no server.
+# AGENTMETRY_MCP_INVENTORY=1
+
 # More tuning: see repo root .env.example and docs/agentmetry-dogfood-checklist.md

{agentmetry-0.9.0 → agentmetry-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.9.0
+Version: 0.9.2
 Summary: Local-first flight recorder for AI coding agents: hash-chained audit trail, MITRE-mapped sequence detection, DLP
 Project-URL: Homepage, https://agentmetry.ai
 Project-URL: Source, https://github.com/blitzcrieg1/agentmetry
@@ -37,7 +37,7 @@ Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=6.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff==0.16.6; extra == 'dev'
+Requires-Dist: ruff==0.16.9; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Agentmetry

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/api/routes/audit.py

@@ -70,6 +70,19 @@ class IngestInitiatorBody(BaseModel):
         return v if v in _ACTOR_TYPES else "agent"
 
 
+class IngestOperatorBody(BaseModel):
+    """Which account the capture process ran as, and how it knew.
+
+    Separate from `initiator`, which says what kind of actor acted. A claim,
+    like everything a client sends: `run_context.resolve_operator` decides what
+    is recorded, and an orchestrator-side AGENTMETRY_OPERATOR_ID overrides an
+    id the hook only read from the operating system.
+    """
+
+    id: str = ""
+    source: str = ""
+
+
 class ExternalIngestBody(BaseModel):
     """Adapter payload — normalized to canonical v1.2 on ingest.
 
@@ -113,6 +126,8 @@ class ExternalIngestBody(BaseModel):
     tool_policy: dict[str, Any] | None = None
     # Who the capture surface says triggered this. Honoured by external.py.
     initiator: IngestInitiatorBody | None = None
+    # Which account ran the agent, resolved by the hook as the developer.
+    operator: IngestOperatorBody | None = None
     # Compact `tools/list` fingerprint from mcp_audit_proxy. Hash only: the
     # description never leaves the proxy process.
     schema_fingerprint: str = ""

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/cli/__init__.py

@@ -284,6 +284,12 @@ def cmd_detections(args: argparse.Namespace) -> int:
     return 0
 
 
+def _triage_operator() -> str:
+    from agentmetry.core.operator_identity import os_operator, stated
+
+    return stated(os.environ.get("AGENTMETRY_OPERATOR_ID", "")) or os_operator()
+
+
 def cmd_disposition(args: argparse.Namespace) -> int:
     """Close a detection from the shell, using the same API as the dashboard."""
     note = args.note.strip()
@@ -299,7 +305,8 @@ def cmd_disposition(args: argparse.Namespace) -> int:
                 "rule_id": args.rule_id,
                 "status": args.status,
                 "note": note,
-                "decided_by": args.decided_by,
+                # The CLI runs as the person triaging; the orchestrator may not.
+                "decided_by": args.decided_by or _triage_operator(),
             },
             headers=_api_headers(),
             timeout=10.0,

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/detection/disposition.py

@@ -431,8 +431,14 @@ def build_disposition_event(
     `action.type:detection_disposition AND action.outcome:risk_accepted`
     without understanding Agentmetry's vocabulary. The note is operator-written
     text, never captured command content, so it is safe to forward.
+
+    Who decided falls back to the resolved operator, not to the raw setting:
+    with AGENTMETRY_OPERATOR_ID unset that was an empty string, so a triage
+    record could not say who triaged.
     """
-    from agentmetry.core.config import settings
+    from agentmetry.core.audit.run_context import resolve_operator
+
+    decided_by = decided_by or resolve_operator()[0]
 
     return {
         "schema_version": SCHEMA_VERSION,
@@ -443,8 +449,8 @@ def build_disposition_event(
         **identity_fields(),
         "source_topic": f"disposition/{rule_id}",
         "source": {"tier": "detection", "app": "agentmetry"},
-        "actor": {"id": decided_by or settings.operator_id, "type": "human"},
-        "initiator": {"type": "human", "id": decided_by or settings.operator_id},
+        "actor": {"id": decided_by, "type": "human"},
+        "initiator": {"type": "human", "id": decided_by},
         "action": {
             "type": DISPOSITION_EVENT_TYPE,
             "outcome": status,
@@ -459,7 +465,7 @@ def build_disposition_event(
             "previous_status": previous_status,
             "assignee": assignee,
             "note": note,
-            "decided_by": decided_by or settings.operator_id,
+            "decided_by": decided_by,
         },
     }
 

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/dlp/loader.py

@@ -4,6 +4,13 @@ from typing import List
 
 from .models import RuleMeta
 
+#: libyaml where it is installed. The pure-Python parser was most of the hook's
+#: runtime: the DLP and tool manifests are re-read by every hook process, and
+#: parsing them took ~55 ms of an ~85 ms tool call (#171). Same SafeConstructor,
+#: so the same Python objects, which `test_hook_import_cost.py` checks.
+SAFE_LOADER = getattr(yaml, "CSafeLoader", yaml.SafeLoader)
+
+
 def load_dlp_rules(manifest_path: Path | str) -> List[RuleMeta]:
     """Load DLP rules from a YAML manifest file."""
     path = Path(manifest_path)
@@ -11,7 +18,7 @@ def load_dlp_rules(manifest_path: Path | str) -> List[RuleMeta]:
         return []
     
     with open(path, "r", encoding="utf-8") as f:
-        data = yaml.safe_load(f)
+        data = yaml.load(f, Loader=SAFE_LOADER)  # noqa: S506 - a safe loader
     
     if not data or "rules" not in data:
         return []

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/dlp/scanner.py

@@ -5,7 +5,9 @@ from typing import Any, Dict
 
 from .models import DlpVerdict, DlpMatch
 from .loader import load_dlp_rules
-from ...config import settings
+# Not core.config: that import is pydantic, and the hook paid ~220 ms for it
+# on every tool call to read three values (#171).
+from ..policy_settings import policy_settings
 
 logger = logging.getLogger(__name__)
 
@@ -21,9 +23,10 @@ def reset_rules() -> None:
 def _init_rules() -> None:
     if _COMPILED_RULES:
         return
-    rules = load_dlp_rules(settings.dlp_rules_path)
+    cfg = policy_settings()
+    rules = load_dlp_rules(cfg.dlp_rules_path)
     for r in rules:
-        if not settings.dlp_pii and r.category == "pii":
+        if not cfg.dlp_pii and r.category == "pii":
             continue
         try:
             _COMPILED_RULES.append((re.compile(r.pattern), r))
@@ -59,7 +62,7 @@ def scan(tool_qualified: str, arguments: Dict[str, Any] | str, mode: str | None
     metadata is returned — never the matched value.
     """
     if mode is None:
-        mode = settings.dlp_mode
+        mode = policy_settings().dlp_mode
     if mode == "disable":
         return DlpVerdict(matched=False, mode=mode)
 

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/evidence_pack.py

@@ -23,6 +23,7 @@ from pathlib import Path
 from typing import Any
 
 from agentmetry.core.audit.detection.disposition import extract_dispositions
+from agentmetry.core.audit.run_context import resolve_operator
 from agentmetry.core.config import settings
 from agentmetry.core.version import __version__
 
@@ -290,7 +291,7 @@ def _controls_snapshot() -> dict[str, Any]:
         "detection": {
             "off_hours_enabled": settings.detect_off_hours,
         },
-        "operator_id": settings.operator_id.strip() or "local",
+        "operator_id": resolve_operator()[0],
     }
 
 

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/external.py

@@ -10,7 +10,11 @@ from agentmetry.core.audit.canonical import SCHEMA_VERSION
 from agentmetry.core.audit.identity import identity_fields
 from agentmetry.core.audit.hashing import arguments_sha256
 from agentmetry.core.audit.redaction import scrub_arg_values, scrub_secrets
-from agentmetry.core.audit.run_context import actor_from_initiator, build_initiator
+from agentmetry.core.audit.run_context import (
+    actor_from_initiator,
+    build_initiator,
+    operator_from_payload,
+)
 from agentmetry.core.config import settings
 
 ExternalApp = Literal[
@@ -34,10 +38,6 @@ _ACTION_MAP = {
 }
 
 
-def _operator_id() -> str:
-    return settings.operator_id.strip() or "local"
-
-
 def _utc_now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
@@ -63,16 +63,18 @@ def build_external_canonical(payload: dict[str, Any]) -> dict[str, Any]:
     correlation_id = str(payload.get("correlation_id") or payload.get("thread_id") or "")
     session_id = str(payload.get("session_id") or "")
 
+    operator = operator_from_payload(payload)
     initiator_raw = payload.get("initiator")
     if isinstance(initiator_raw, dict) and initiator_raw.get("actor_type"):
         initiator = {
             "actor_type": str(initiator_raw.get("actor_type") or "human"),
             "trigger": str(initiator_raw.get("trigger") or "manual"),
-            "operator_id": str(initiator_raw.get("operator_id") or _operator_id()),
+            "operator_id": operator[0],
+            "operator_source": operator[1],
         }
     else:
         trigger = str(payload.get("triggered_by") or "manual")
-        initiator = build_initiator(trigger)
+        initiator = build_initiator(trigger, operator)
 
     tool_block = payload.get("tool") if isinstance(payload.get("tool"), dict) else {}
     tool_qualified = str(

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/heartbeat.py

@@ -297,11 +297,14 @@ async def heartbeat_forever(interval: float | None = None) -> None:
     """
     import asyncio
 
+    from agentmetry.core.audit.mcp_inventory_event import InventoryState, maybe_emit_inventory
+
     period = interval if interval is not None else interval_seconds()
     if not period:
         logger.info("Heartbeat disabled (AGENTMETRY_HEARTBEAT_SECONDS=0)")
         return
 
+    inventory_state = InventoryState()
     while True:
         try:
             event = await emit_heartbeat()
@@ -310,4 +313,10 @@ async def heartbeat_forever(interval: float | None = None) -> None:
         except Exception:
             # Never let attestation kill the recorder it attests for.
             logger.exception("Heartbeat failed")
+        try:
+            # Opt-in (#169). Separate from the beat, so the beat stays
+            # name-free, and in its own try, so it cannot stop the beat.
+            await maybe_emit_inventory(inventory_state)
+        except Exception:
+            logger.exception("MCP inventory event failed")
         await asyncio.sleep(period)

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/ingest.py

@@ -144,6 +144,7 @@ def _get_sink():
         webhook_url=settings.audit_webhook_url,
         webhook_timeout_seconds=settings.audit_webhook_timeout_seconds,
         webhook_format=settings.audit_webhook_format,
+        webhook_token=settings.audit_webhook_token,
         elastic_url=settings.audit_elastic_url,
         elastic_index=settings.audit_elastic_index,
         elastic_api_key=settings.audit_elastic_api_key,

agentmetry-0.9.2/agentmetry/core/audit/mcp_inventory_event.py

@@ -0,0 +1,119 @@
+"""The configured MCP servers as an event a SIEM can see, when an operator asks (#169).
+
+`agentmetry mcp` answers "what are the agents on this machine wired to", but
+only for whoever runs it, on that machine. Nothing reached the trail, so no SIEM
+could answer "which machines have this server" or "when did it first appear".
+
+This is deliberately not the heartbeat. The heartbeat goes to every sink on
+every install and commits to the MCP surface by digest alone, so that recording
+your own laptop never ships your tool inventory to a SOC. That property stays.
+The inventory is a separate event, off unless `AGENTMETRY_MCP_INVENTORY=1`, for
+the fleet that wants it.
+
+When on, it is emitted when the recorder starts, whenever the configured
+surface changes, and once a day regardless, so a dashboard over the last 24
+hours sees every host. Each server is reduced to `McpServer.wire_entry()`: no
+arguments, no environment, no URL beyond its host.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from dataclasses import dataclass
+from typing import Any
+
+from agentmetry.core.audit.canonical import SCHEMA_VERSION
+from agentmetry.core.audit.identity import identity_fields
+
+logger = logging.getLogger(__name__)
+
+#: Re-emit an unchanged inventory this often, so a fleet view over a day is whole.
+SNAPSHOT_SECONDS = 24 * 3600
+
+#: The event goes to every sink. A machine with more servers than this is
+#: reported by count, with the list cut and `truncated` set.
+LIMIT = 100
+
+
+def enabled() -> bool:
+    from agentmetry.core.config import settings
+
+    return bool(getattr(settings, "mcp_inventory_enabled", False))
+
+
+@dataclass
+class InventoryState:
+    """What was last emitted, so an unchanged surface is not re-sent every beat."""
+
+    digest: str | None = None
+    emitted_at: float = 0.0
+
+
+def build_inventory_event(now_utc: str, inventory: Any, *, outcome: str) -> dict[str, Any]:
+    servers = list(inventory.servers)
+    entries = [s.wire_entry() for s in servers[:LIMIT]]
+    flagged = sum(1 for e in entries if e["findings"])
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "event_id": str(uuid.uuid4()),
+        "session_id": "",
+        "correlation_id": "",
+        "timestamp_utc": now_utc,
+        **identity_fields(),
+        "source_topic": "agentmetry/mcp_inventory",
+        "source": {"tier": "agentmetry", "app": "agentmetry", "adapter": "mcp_inventory"},
+        "initiator": {"actor_type": "system", "trigger": "scheduled", "operator_id": ""},
+        "actor": {"type": "system", "id": "agentmetry", "role": "recorder"},
+        "action": {
+            "type": "mcp_inventory",
+            "outcome": outcome,
+            "reason": f"{len(servers)} MCP server(s) configured, {flagged} flagged",
+        },
+        "agent": {"name": "agentmetry", "skill_id": ""},
+        "mcp_inventory": {
+            "servers": entries,
+            "server_count": len(servers),
+            "truncated": len(servers) > LIMIT,
+            "config_digest": inventory.digest()[:16] if servers else "",
+            "files_read": len(inventory.files_read),
+            "files_unreadable": len(inventory.unreadable),
+        },
+    }
+
+
+def due(state: InventoryState, digest: str, now_monotonic: float) -> str | None:
+    """`snapshot`, `changed`, or None when there is nothing to say."""
+    if state.digest is None:
+        return "snapshot"
+    if digest != state.digest:
+        return "changed"
+    if now_monotonic - state.emitted_at >= SNAPSHOT_SECONDS:
+        return "snapshot"
+    return None
+
+
+async def maybe_emit_inventory(state: InventoryState) -> dict[str, Any] | None:
+    """Emit the inventory if the operator turned it on and there is news."""
+    if not enabled():
+        return None
+    from datetime import datetime, timezone
+
+    from agentmetry.core.audit.ingest import _get_sink
+    from agentmetry.core.audit.trail_db import get_trail_db
+    from agentmetry.core.diagnostics.mcp_inventory import collect
+
+    inventory = collect()
+    digest = inventory.digest() if inventory.servers else ""
+    now = time.monotonic()
+    outcome = due(state, digest, now)
+    if outcome is None:
+        return None
+    event = build_inventory_event(datetime.now(timezone.utc).isoformat(), inventory, outcome=outcome)
+    # The heartbeat's durability contract: the local insert is the guarantee,
+    # network sinks swallow their own failures.
+    get_trail_db().insert(event)
+    await _get_sink().emit(event)
+    state.digest, state.emitted_at = digest, now
+    return event

{agentmetry-0.9.0 → agentmetry-0.9.2}/agentmetry/core/audit/otel_ingest.py

@@ -276,7 +276,7 @@ def _map_tool_decision(attrs: dict[str, Any], ts_iso: str) -> tuple[dict[str, An
             "outcome": "success",
             "reason": f"otel_decision:{source}",
             "tool_qualified": str(attrs.get("tool_name") or ""),
-            "initiator": {"actor_type": "human", "trigger": "manual", "operator_id": "local"},
+            "initiator": {"actor_type": "human", "trigger": "manual", "operator_id": ""},
         })
         return payload, ""
     if decision == "reject" and source in _HUMAN_REJECT:

agentmetry-0.9.2/agentmetry/core/audit/policy_settings.py

@@ -0,0 +1,162 @@
+"""The five settings DLP and tool policy read, without importing pydantic (#171).
+
+The hook runs in front of every tool call, and on a blocking hook the agent waits
+for it. The DLP scanner and the tool-policy evaluator used to import
+`core.config` to learn a mode and a manifest path each, and that one import
+pulled in pydantic and pydantic-settings: about 220 ms of a 626 ms hook, paid on
+every tool call to read five values.
+
+So there are two ways to get them, and one answer:
+
+* Where `core.config` is already loaded, the orchestrator and the test suite,
+  the real `settings` object is read. A test that monkeypatches
+  `settings.dlp_mode` still changes what the scanner sees.
+* Where it is not, the hook, they are resolved here the way `Settings` resolves
+  them: environment first, matched case-insensitively, then the orchestrator's
+  `.env`, then the same defaults. `test_hook_import_cost.py` checks the two
+  agree.
+
+Standard library only. That is the whole point of the module.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+_HERE = Path(__file__).resolve()
+_PACKAGE_ROOT = _HERE.parents[2]       # agentmetry/, as config._PACKAGE_ROOT
+_ORCHESTRATOR_ROOT = _HERE.parents[3]  # where Settings reads .env, as config._ORCHESTRATOR_ROOT
+
+#: pydantic's own boolean vocabulary, so `AGENTMETRY_DLP_PII=off` means the same
+#: thing to the hook as to the orchestrator.
+_TRUE = frozenset({"1", "on", "t", "true", "y", "yes"})
+_FALSE = frozenset({"0", "off", "f", "false", "n", "no"})
+
+_DOTENV_CACHE: tuple[tuple[str, float, int] | None, dict[str, str]] = (None, {})
+
+
+@dataclass(frozen=True)
+class PolicySettings:
+    dlp_mode: str
+    dlp_rules_path: Path
+    dlp_pii: bool
+    tool_policy_mode: str
+    tool_policy_path: Path
+
+
+def _defaults() -> PolicySettings:
+    policies = _PACKAGE_ROOT / "policies"
+    return PolicySettings(
+        dlp_mode="log",
+        dlp_rules_path=policies / "dlp" / "manifest.yaml",
+        dlp_pii=True,
+        tool_policy_mode="log",
+        tool_policy_path=policies / "tool" / "manifest.yaml",
+    )
+
+
+def _parse_dotenv(text: str) -> dict[str, str]:
+    """The subset of python-dotenv that a `.env` for this project uses.
+
+    `export` prefixes, single or double quotes, and a ` #` comment after an
+    unquoted value. Keys are lowercased, because Settings matches them
+    case-insensitively.
+    """
+    out: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):].lstrip()
+        key, _, value = line.partition("=")
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        elif " #" in value:
+            value = value.split(" #", 1)[0].rstrip()
+        out[key.strip().lower()] = value
+    return out
+
+
+def _dotenv() -> dict[str, str]:
+    """The orchestrator's `.env`, parsed once per change to the file."""
+    global _DOTENV_CACHE
+    path = _ORCHESTRATOR_ROOT / ".env"
+    try:
+        stat = path.stat()
+    except OSError:
+        return {}
+    stamp = (str(path), stat.st_mtime, stat.st_size)
+    if _DOTENV_CACHE[0] == stamp:
+        return _DOTENV_CACHE[1]
+    try:
+        parsed = _parse_dotenv(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError):
+        return {}
+    _DOTENV_CACHE = (stamp, parsed)
+    return parsed
+
+
+def _lookup(name: str, environ: dict[str, str], dotenv: dict[str, str]) -> str | None:
+    # Present-but-empty counts as set, as it does for Settings (env_ignore_empty
+    # is off): an empty mode is not "use the default".
+    key = name.lower()
+    if key in environ:
+        return environ[key]
+    return dotenv.get(key)
+
+
+def _bool(raw: str | None, default: bool) -> bool:
+    if raw is None:
+        return default
+    text = raw.strip().lower()
+    if text in _TRUE:
+        return True
+    if text in _FALSE:
+        return False
+    # Settings refuses to start on this. The hook must not fail a tool call over
+    # a typo, so it keeps the default and the orchestrator's error stays the
+    # place the operator finds out.
+    return default
+
+
+def resolve() -> PolicySettings:
+    """Resolve without pydantic, as the hook does."""
+    environ = {k.lower(): v for k, v in os.environ.items()}
+    dotenv = _dotenv()
+    base = _defaults()
+
+    def text(name: str, default: str) -> str:
+        value = _lookup(name, environ, dotenv)
+        return default if value is None else value
+
+    def path(name: str, default: Path) -> Path:
+        value = _lookup(name, environ, dotenv)
+        return default if value is None else Path(value)
+
+    return PolicySettings(
+        dlp_mode=text("AGENTMETRY_DLP_MODE", base.dlp_mode),
+        dlp_rules_path=path("AGENTMETRY_DLP_RULES_PATH", base.dlp_rules_path),
+        dlp_pii=_bool(_lookup("AGENTMETRY_DLP_PII", environ, dotenv), base.dlp_pii),
+        tool_policy_mode=text("AGENTMETRY_TOOL_POLICY_MODE", base.tool_policy_mode),
+        tool_policy_path=path("AGENTMETRY_TOOL_POLICY_PATH", base.tool_policy_path),
+    )
+
+
+def policy_settings() -> PolicySettings:
+    """The settings, from the loaded `Settings` object when there is one."""
+    config = sys.modules.get("agentmetry.core.config")
+    settings = getattr(config, "settings", None) if config is not None else None
+    if settings is None:
+        return resolve()
+    return PolicySettings(
+        dlp_mode=settings.dlp_mode,
+        dlp_rules_path=Path(settings.dlp_rules_path),
+        dlp_pii=bool(settings.dlp_pii),
+        tool_policy_mode=settings.tool_policy_mode,
+        tool_policy_path=Path(settings.tool_policy_path),
+    )