agentmetry 0.9.1__tar.gz → 0.9.2__tar.gz

{agentmetry-0.9.1 → 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.1 → agentmetry-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.9.1
+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.1 → agentmetry-0.9.2}/agentmetry/cli/__init__.py

@@ -285,12 +285,9 @@ def cmd_detections(args: argparse.Namespace) -> int:
 
 
 def _triage_operator() -> str:
-    configured = os.environ.get("AGENTMETRY_OPERATOR_ID", "").strip()
-    if configured:
-        return configured
-    from agentmetry.core.operator_identity import os_operator
+    from agentmetry.core.operator_identity import os_operator, stated
 
-    return os_operator()
+    return stated(os.environ.get("AGENTMETRY_OPERATOR_ID", "")) or os_operator()
 
 
 def cmd_disposition(args: argparse.Namespace) -> int:

{agentmetry-0.9.1 → 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.1 → 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.1 → agentmetry-0.9.2}/agentmetry/core/audit/run_context.py

@@ -49,7 +49,7 @@ def resolve_operator(client_id: object = "", client_source: object = "") -> tupl
     source = str(client_source or "")
     if claimed and source == oid.CONFIGURED:
         return claimed, oid.HOOK_CONFIGURED
-    configured = settings.operator_id.strip()
+    configured = oid.stated(settings.operator_id)
     if configured:
         return configured, oid.ORCHESTRATOR_CONFIGURED
     if claimed:

{agentmetry-0.9.1 → agentmetry-0.9.2}/agentmetry/core/audit/sinks.py

@@ -50,11 +50,17 @@ class WebhookAuditSink(AuditSink):
     """
 
     def __init__(
-        self, url: str, *, timeout_seconds: float = 5.0, format: str = "canonical"
+        self,
+        url: str,
+        *,
+        timeout_seconds: float = 5.0,
+        format: str = "canonical",
+        token: str = "",
     ) -> None:
         self._url = url
         self._timeout = timeout_seconds
         self._cloudevents = (format or "").strip().lower() in ("cloudevents", "cloudevent", "ce")
+        self._token = (token or "").strip()
 
     async def emit(self, canonical: dict[str, Any]) -> None:
         payload = canonical
@@ -66,12 +72,15 @@ class WebhookAuditSink(AuditSink):
 
             payload = canonical_to_cloudevent(canonical)
             content_type = "application/cloudevents+json; charset=utf-8"
+        headers = {"Content-Type": content_type, "User-Agent": "Agentmetry/1.0"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
         try:
             async with httpx.AsyncClient(timeout=self._timeout) as client:
                 response = await client.post(
                     self._url,
                     json=payload,
-                    headers={"Content-Type": content_type, "User-Agent": "Agentmetry/1.0"},
+                    headers=headers,
                 )
                 response.raise_for_status()
         except Exception:
@@ -285,6 +294,7 @@ def build_audit_sinks(
     webhook_url: str,
     webhook_timeout_seconds: float,
     webhook_format: str = "canonical",
+    webhook_token: str = "",
     elastic_url: str,
     elastic_index: str,
     elastic_api_key: str,
@@ -311,6 +321,7 @@ def build_audit_sinks(
                 webhook_url.strip(),
                 timeout_seconds=webhook_timeout_seconds,
                 format=webhook_format,
+                token=webhook_token,
             )
         )
 

{agentmetry-0.9.1 → agentmetry-0.9.2}/agentmetry/core/bus/audit_exporter.py

@@ -58,6 +58,7 @@ async def audit_exporter(
         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.1 → agentmetry-0.9.2}/agentmetry/core/config.py

@@ -100,6 +100,13 @@ class Settings(BaseSettings):
         default="canonical",
         validation_alias=AliasChoices("AGENTMETRY_AUDIT_WEBHOOK_FORMAT"),
     )
+    # Optional bearer token on every webhook POST. A hosted ingest that binds
+    # tenant and host to the token needs this header; an existing webhook that
+    # never asked for auth keeps receiving unauthenticated requests, unchanged.
+    audit_webhook_token: str = Field(
+        default="",
+        validation_alias=AliasChoices("AGENTMETRY_AUDIT_WEBHOOK_TOKEN"),
+    )
     audit_elastic_url: str = Field(
         default="",
         validation_alias=AliasChoices(
@@ -200,6 +207,14 @@ class Settings(BaseSettings):
         _policy("detection", "manifest.yaml")
     )
 
+    # The configured MCP servers as an `mcp_inventory` event, for a fleet that
+    # wants them in the SIEM (#169). Off by default: the heartbeat names no
+    # server, and turning this on is the operator's decision, not ours.
+    mcp_inventory_enabled: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("AGENTMETRY_MCP_INVENTORY"),
+    )
+
     # Demo MCP vault — doctor, drivers.json, vault_fs server (not a skill runtime).
     vault_path: Path = Path(__file__).resolve().parents[4] / "vault"
 

{agentmetry-0.9.1 → agentmetry-0.9.2}/agentmetry/core/diagnostics/mcp_inventory.py

@@ -37,6 +37,7 @@ import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Iterable
+from urllib.parse import urlparse
 
 #: Fetch-and-run launchers. These resolve a package over the network on every
 #: invocation, so the bytes executed are decided later than the config was read.
@@ -92,6 +93,48 @@ class McpServer:
         )
         return hashlib.sha256(material.encode()).hexdigest()
 
+    def finding_codes(self) -> list[str]:
+        """`findings()` as stable codes a SIEM can group on, carrying no values."""
+        codes: list[str] = []
+        if self.transport == "stdio":
+            if not self.command:
+                return ["no_command"]
+            launcher = Path(self.command).stem.lower()
+            spec = self.spec()
+            if _FETCHING_LAUNCHER.match(launcher) and spec and not _PINNED_SPEC.match(spec):
+                codes.append("unpinned_fetch")
+                if _AUTO_YES & set(self.args):
+                    codes.append("auto_confirm")
+        elif self.url.startswith("http://"):
+            codes.append("plaintext_http")
+        return codes
+
+    def wire_entry(self) -> dict[str, Any]:
+        """What a heartbeat may carry about this server, off this machine (#169).
+
+        Enough to inventory a fleet from the SIEM: which agent, which server,
+        how it is launched, whether it is flagged. Nothing that tends to hold a
+        secret. Arguments carry tokens and home-directory paths, so they are
+        left out, and so are env values and env keys. A URL keeps only its host,
+        because query strings carry API keys. The package name is kept only for
+        a fetch-and-run launcher, where it is a public registry name and is the
+        thing worth knowing. The fingerprint commits to all of it, so a changed
+        argument still changes the entry without the argument being shown.
+        """
+        launcher = Path(self.command).stem.lower() if self.command else ""
+        fetching = bool(launcher and _FETCHING_LAUNCHER.match(launcher))
+        return {
+            "agent": self.agent,
+            "name": self.name,
+            "scope": self.scope,
+            "transport": self.transport,
+            "launcher": launcher,
+            "package": self.spec() if fetching else "",
+            "url_host": (urlparse(self.url).hostname or "") if self.url else "",
+            "findings": self.finding_codes(),
+            "fingerprint": self.fingerprint()[:16],
+        }
+
     def findings(self) -> list[str]:
         """Configuration facts worth an operator's attention."""
         out: list[str] = []

{agentmetry-0.9.1 → agentmetry-0.9.2}/agentmetry/core/operator_identity.py

@@ -75,6 +75,13 @@ def windows_account(environ: Mapping[str, str]) -> str:
 
 
 def stated(value: object) -> str:
-    """A client-supplied id, or empty when it said nothing or the legacy constant."""
+    """An id somebody actually stated, or empty.
+
+    Empty for nothing, and for `local`, whether a hook sent it or a `.env` says
+    it. Both `.env.example` files shipped `AGENTMETRY_OPERATOR_ID=local` up to
+    0.9.1 and both installers copied it, so on an installed machine `local` in
+    the config is the old placeholder, not a choice. Read as configured, it
+    overrode the OS account and every event said `local` again.
+    """
     text = str(value or "").strip()
     return "" if text == LEGACY_PLACEHOLDER else text

{agentmetry-0.9.1 → agentmetry-0.9.2}/agentmetry/core/version.py

@@ -10,4 +10,4 @@ Bump this here and add the matching CHANGELOG section in the same commit.
 
 from __future__ import annotations
 
-__version__ = "0.9.1"
+__version__ = "0.9.2"

{agentmetry-0.9.1 → agentmetry-0.9.2}/agentmetry/hooks/ingest.py

@@ -61,10 +61,14 @@ except ImportError:  # pragma: no cover - the package always ships it
 # Standard library only, so it costs the hook nothing. Guarded anyway: an
 # unresolvable operator must leave the event unattributed, not unrecorded.
 try:
-    from agentmetry.core.operator_identity import os_operator
+    from agentmetry.core.operator_identity import os_operator, stated
 except ImportError:  # pragma: no cover - the package always ships it
     os_operator = None
 
+    def stated(value: object) -> str:
+        text = str(value or "").strip()
+        return "" if text == "local" else text
+
 # Separate try: a DLP import failure (missing yaml/pydantic) must not also kill
 # trait/MITRE tagging, which only needs the stdlib.
 try:
@@ -547,9 +551,10 @@ def _operator() -> dict[str, str]:
     """
     global _OPERATOR
     if _OPERATOR is None:
-        configured = (
-            os.environ.get("AGENTMETRY_OPERATOR_ID", "").strip()
-            or _read_repo_env("AGENTMETRY_OPERATOR_ID").strip()
+        # `local` is the placeholder .env.example used to ship, not a choice.
+        configured = stated(
+            os.environ.get("AGENTMETRY_OPERATOR_ID", "")
+            or _read_repo_env("AGENTMETRY_OPERATOR_ID")
         )
         if configured:
             _OPERATOR = {"id": configured, "source": "configured"}

{agentmetry-0.9.1 → agentmetry-0.9.2}/pyproject.toml

@@ -52,7 +52,7 @@ dependencies = [
 # so a linter release could turn a green branch red with no change to this repo.
 # It did: 0.16.0 widened the default rule set and CI reported 132 errors against
 # code that passed locally on 0.15.x. Bump this deliberately, not by accident.
-dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "pytest-cov>=6.0", "ruff==0.16.6"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.24", "pytest-cov>=6.0", "ruff==0.16.9"]
 
 [project.urls]
 Homepage = "https://agentmetry.ai"

{agentmetry-0.9.1 → agentmetry-0.9.2}/tests/test_audit_sinks.py

@@ -53,6 +53,71 @@ async def test_webhook_sink_posts_json():
     mock_client.post.assert_awaited_once()
 
 
+@pytest.mark.asyncio
+async def test_webhook_sink_sends_bearer_token_when_configured():
+    """A hosted ingest binds tenant and host to the token, so the header must
+    arrive on every POST — canonical and CloudEvents shapes alike."""
+    sink = WebhookAuditSink(
+        "http://collector.test/ingest", timeout_seconds=2.0, token="agm-test-token"
+    )
+    payload = {"action": {"type": "tool_called", "outcome": "success"}}
+
+    mock_response = AsyncMock()
+    mock_response.raise_for_status = lambda: None
+    mock_client = AsyncMock()
+    mock_client.post = AsyncMock(return_value=mock_response)
+    mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+    mock_client.__aexit__ = AsyncMock(return_value=None)
+
+    with patch("agentmetry.core.audit.sinks.httpx.AsyncClient", return_value=mock_client):
+        await sink.emit(payload)
+
+    headers = mock_client.post.await_args.kwargs["headers"]
+    assert headers["Authorization"] == "Bearer agm-test-token"
+
+
+@pytest.mark.asyncio
+async def test_webhook_sink_omits_authorization_without_token():
+    """Existing webhooks that never asked for auth must keep receiving
+    unauthenticated requests: no token configured, no header sent."""
+    sink = WebhookAuditSink("http://collector.test/ingest", timeout_seconds=2.0)
+    payload = {"action": {"type": "tool_called", "outcome": "success"}}
+
+    mock_response = AsyncMock()
+    mock_response.raise_for_status = lambda: None
+    mock_client = AsyncMock()
+    mock_client.post = AsyncMock(return_value=mock_response)
+    mock_client.__aenter__ = AsyncMock(return_value=mock_client)
+    mock_client.__aexit__ = AsyncMock(return_value=None)
+
+    with patch("agentmetry.core.audit.sinks.httpx.AsyncClient", return_value=mock_client):
+        await sink.emit(payload)
+
+    assert "Authorization" not in mock_client.post.await_args.kwargs["headers"]
+
+
+def test_build_audit_sinks_plumbs_webhook_token():
+    sink = build_audit_sinks(
+        modes={"webhook"},
+        file_path=Path("unused.jsonl"),
+        webhook_url="http://collector.test/ingest",
+        webhook_timeout_seconds=2.0,
+        webhook_format="canonical",
+        webhook_token="agm-plumbed",
+        elastic_url="",
+        elastic_index="",
+        elastic_api_key="",
+        elastic_verify_tls=True,
+        splunk_hec_url="",
+        splunk_hec_token="",
+        splunk_index="",
+        splunk_sourcetype="",
+        splunk_verify_tls=True,
+    )
+    assert isinstance(sink, WebhookAuditSink)
+    assert sink._token == "agm-plumbed"
+
+
 @pytest.mark.asyncio
 async def test_elastic_sink_posts_ecs_document():
     canonical = {