agentmetry 0.4.0__tar.gz → 0.6.0__tar.gz

{agentmetry-0.4.0 → agentmetry-0.6.0}/.env.example

@@ -17,4 +17,11 @@ AGENTMETRY_DLP_MODE=log
 AGENTMETRY_AUDIT_EXPORT_ENABLED=1
 AGENTMETRY_AUDIT_SINK=file
 
+# Anchor log, when it is not the file sitting beside the trail. Point this at a
+# working copy of a remote this machine cannot rewrite and `verify --trail` and
+# `doctor` will check against it without being handed --anchors. Unset is fine:
+# the chain still verifies, it just cannot survive an attacker who owns this
+# host. See docs/anchoring.md.
+# AGENTMETRY_ANCHOR_LOG=../agentmetry-anchors/home-lab/agentmetry-trail.anchors.jsonl
+
 # More tuning: see repo root .env.example and docs/agentmetry-dogfood-checklist.md

{agentmetry-0.4.0 → agentmetry-0.6.0}/.gitignore

@@ -96,3 +96,7 @@ docs/*-review-*.md
 docs/*audit*prompt*.md
 docs/audit-*.md
 docs/*-audit-*.md
+
+# pytest-cov data file
+.coverage
+.coverage.*

{agentmetry-0.4.0 → agentmetry-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.4.0
+Version: 0.6.0
 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
@@ -35,8 +35,9 @@ Requires-Dist: uvicorn[standard]>=0.32.0
 Requires-Dist: websockets>=14.0
 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.0; extra == 'dev'
+Requires-Dist: ruff==0.16.4; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Agentmetry

{agentmetry-0.4.0 → agentmetry-0.6.0}/agentmetry/api/main.py

@@ -78,6 +78,7 @@ async def lifespan(app: FastAPI):
     # time — so every hook that fires during the drain is refused and spooled,
     # which makes the next drain larger. The recorder has to be reachable first
     # and catch up second.
+    from agentmetry.core.audit.heartbeat import heartbeat_forever
     from agentmetry.core.audit.spool import drain_forever, drain_spool
 
     async def _boot_drain() -> None:
@@ -108,6 +109,10 @@ async def lifespan(app: FastAPI):
         # backlog growing unnoticed whenever ingest is unreachable while the
         # process itself stays up.
         asyncio.create_task(drain_forever(), name="spool-drain"),
+        # Attest on an interval so a machine that goes quiet is distinguishable
+        # from a machine whose hooks were removed. Absence only means something
+        # if presence was being asserted.
+        asyncio.create_task(heartbeat_forever(), name="heartbeat"),
     ]
 
     # Drivers mount in the background: a slow npx download must not delay boot.

{agentmetry-0.4.0 → agentmetry-0.6.0}/agentmetry/api/routes/audit.py

@@ -51,7 +51,7 @@ class ExternalIngestBody(BaseModel):
     )
     event_type: str = Field(
         ...,
-        description="session_start | session_end | tool_called | tool_denied | tool_failed | approval_request | approval_response",
+        description="session_start | session_end | tool_called | tool_denied | tool_failed | approval_request | approval_response | mcp_schema",
     )
     correlation_id: str = ""
     session_id: str = ""
@@ -71,6 +71,10 @@ class ExternalIngestBody(BaseModel):
     # pydantic drops it and a `log`-mode match is silently lost.
     dlp: dict[str, Any] | None = None
     tool_policy: dict[str, Any] | None = None
+    # Compact `tools/list` fingerprint from mcp_audit_proxy. Hash only: the
+    # description never leaves the proxy process.
+    schema_fingerprint: str = ""
+    schema_tool_count: int = 0
 
 
 def _parse_event_ts(event: dict[str, Any]) -> datetime | None:

{agentmetry-0.4.0 → agentmetry-0.6.0}/agentmetry/cli/__init__.py

@@ -7,6 +7,7 @@ Pure stdlib + httpx; never imports the FastAPI app (fast startup, no side effect
 from __future__ import annotations
 
 import argparse
+import logging
 import os
 import shutil
 import socket
@@ -30,11 +31,13 @@ _TASK_NAME = "Agentmetry Orchestrator"
 # Paths bundled by backup, relative to the repo root.
 _BACKUP_PREFIXES = ("vault/", "apps/orchestrator/data/")
 _BACKUP_EXCLUDE_DIRS = {"logs"}
+logger = logging.getLogger(__name__)
+
 _BACKUP_EXCLUDE_SUFFIXES = {".pid"}
 
 
 def _base_url(port: int, host: str = "127.0.0.1") -> str:
-    display = host if host != "0.0.0.0" else "127.0.0.1"
+    display = host if host != "0.0.0.0" else "127.0.0.1"  # noqa: S104
     return f"http://{display}:{port}"
 
 
@@ -65,8 +68,12 @@ def _fetch_health(port: int) -> dict | None:
         resp = httpx.get(f"{_base_url(port)}/api/v1/health", timeout=10.0)
         if resp.status_code == 200:
             return resp.json()
-    except Exception:
-        pass
+    except Exception as exc:
+        # Not running is the expected answer here and `None` says so. Logged at
+        # debug anyway: a probe that fails for a reason other than "nothing is
+        # listening" (TLS, a proxy, a permission error) otherwise looks identical
+        # to a stopped orchestrator, and that is an hour of somebody's afternoon.
+        logger.debug("health probe on port %s failed: %s", port, exc)
     return None
 
 
@@ -77,7 +84,7 @@ def cmd_start(args: argparse.Namespace) -> int:
     host = getattr(args, "host", "127.0.0.1")
     if _fetch_health(args.port):
         print(f"Already running on {_base_url(args.port, host)}")
-        if host == "0.0.0.0":
+        if host == "0.0.0.0":  # noqa: S104
             _print_lan_hint(args.port)
         return 0
 
@@ -112,7 +119,7 @@ def cmd_start(args: argparse.Namespace) -> int:
     while time.monotonic() < deadline:
         if _fetch_health(args.port):
             print(f"Agentmetry running on {_base_url(args.port, host)} (pid {proc.pid})")
-            if host == "0.0.0.0":
+            if host == "0.0.0.0":  # noqa: S104
                 _print_lan_hint(args.port)
             return 0
         if proc.poll() is not None:
@@ -395,6 +402,130 @@ def cmd_install(args: argparse.Namespace) -> int:
     return 0
 
 
+#: Agents this CLI can install for. Antigravity is absent on purpose: its hooks
+#: live in ~/.gemini and are written by scripts/install_antigravity_hooks.ps1,
+#: which has no Python equivalent. Listing it here and quietly doing nothing
+#: would be the reporting failure this codebase keeps finding in itself.
+_HOOK_INSTALLERS = ("cursor", "claude", "codex", "qwen", "kimi", "qoder", "codebuddy")
+
+
+def _hooks_status() -> int:
+    """Coverage as an exit code, for a deployment tool rather than a person.
+
+    Intune Remediations, and every scheduled-check mechanism like it, want a
+    detection script whose exit code is the answer. Parsing `doctor` output
+    would work until somebody reworded a line, and a coverage check that breaks
+    silently on a wording change is worse than no check.
+
+    The contract:
+      0  every agent present here is recorded, or none is installed
+      1  at least one agent is present and not recorded, and installing helps
+      2  coverage cannot be determined, and installing would not help
+
+    2 is separate from 1 on purpose. A service profile sees no developer's
+    configuration at all, so remediation there would run forever and fix
+    nothing. Reporting it as compliant would be the lie this whole subsystem
+    exists to prevent, so it is neither.
+    """
+    from agentmetry.core.diagnostics import hook_coverage
+
+    if hook_coverage.is_service_profile():
+        print(
+            "UNDETERMINABLE: running under a service profile. Hook configuration "
+            "lives in each developer's profile and none is visible from here. "
+            "Run this in the user's context.",
+            file=sys.stderr,
+        )
+        return 2
+
+    states = hook_coverage.coverage()
+    for line in hook_coverage.summary_lines(states):
+        print(line.strip())
+
+    uncovered = hook_coverage.uncovered(states)
+    if uncovered:
+        print(f"NEEDS REMEDIATION: {', '.join(uncovered)}")
+        return 1
+    print("COMPLIANT")
+    return 0
+
+
+def cmd_hooks(args: argparse.Namespace) -> int:
+    """Install hook configs, defaulting to the agents actually on this machine.
+
+    The default matters more than it looks. This is what a per-user deployment
+    step runs at first logon, where nobody knows in advance which IDEs that
+    developer uses. Installing for all seven would write configs for agents that
+    are not there; installing for two would miss the ones they do use.
+    """
+    from agentmetry.core.audit import hook_bootstrap
+    from agentmetry.core.diagnostics import hook_coverage
+
+    if args.action == "status":
+        return _hooks_status()
+
+    if hook_bootstrap.hook_target() == "none":
+        print(
+            "No way to reach ingest from here: no checkout, no frozen binary, no "
+            "agentmetry-hook script. Installing hook configs now would write "
+            "commands that cannot run.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.agent:
+        wanted = [a for a in args.agent if a in _HOOK_INSTALLERS]
+        unknown = sorted(set(args.agent) - set(wanted))
+        if unknown:
+            print(f"No installer for: {', '.join(unknown)}", file=sys.stderr)
+            return 2
+    elif args.all:
+        wanted = list(_HOOK_INSTALLERS)
+    else:
+        states = hook_coverage.coverage()
+        wanted = [a for a in _HOOK_INSTALLERS if states.get(a) != hook_coverage.ABSENT]
+        if not wanted:
+            print("No supported agent found on this machine; nothing to install.")
+            return 0
+
+    failures = 0
+    for agent in wanted:
+        install = getattr(hook_bootstrap, f"install_{agent}_global_hooks", None)
+        if install is None:
+            print(f"  {agent}: no installer", file=sys.stderr)
+            failures += 1
+            continue
+        try:
+            path = install()
+        except OSError as exc:
+            print(f"  {agent}: FAILED ({exc})", file=sys.stderr)
+            failures += 1
+            continue
+        if path is None:
+            print(f"  {agent}: skipped", file=sys.stderr)
+            failures += 1
+        else:
+            print(f"  {agent}: {path}")
+
+    if "codex" in wanted and not failures:
+        print("")
+        print("codex: open Codex, run /hooks and approve the entries, or it")
+        print("skips them silently and records nothing.")
+    return 1 if failures else 0
+
+
+def cmd_hook(args: argparse.Namespace) -> int:
+    """Forward one hook event. Present here for discoverability and docs.
+
+    Hook configs should name the `agentmetry-hook` console script instead. This
+    path imports the whole CLI module, including httpx, on a code path that runs
+    once per tool call, and a hook has no reason to pay for that.
+    """
+    from agentmetry.hooks.ingest import main as ingest_main
+
+    return ingest_main([args.app, "hook", args.event])
+
+
 def cmd_uninstall(args: argparse.Namespace) -> int:
     from agentmetry.core.diagnostics import autostart
 
@@ -655,6 +786,110 @@ def cmd_prove(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_mcp(args: argparse.Namespace) -> int:
+    """List the MCP servers the agents on this machine are wired to.
+
+    The trail answers what an agent did. This answers what it was allowed to
+    reach, which is the question asked first in every security review and the one
+    a behavioural record cannot reconstruct after the fact.
+    """
+    from pathlib import Path as _Path
+
+    from agentmetry.core.diagnostics.mcp_inventory import collect, summary_lines
+
+    inv = collect(_Path(args.project).resolve() if args.project else _Path.cwd())
+    for line in summary_lines(inv):
+        print(line)
+    from agentmetry.core.diagnostics.mcp_schema import schema_summary_lines
+
+    for line in schema_summary_lines():
+        print(line)
+
+    if args.digest:
+        # Safe to publish beside a trail anchor: it commits to the configured
+        # surface without naming a single server.
+        print(inv.digest())
+    # Findings describe a risk posture, not a broken install, so they are
+    # reported rather than turned into a non-zero exit that would break a
+    # health check somebody wired into MDM.
+    return 0
+
+
+def cmd_anchor(args: argparse.Namespace) -> int:
+    """Publish, list, or check the checkpoints that commit the trail externally.
+
+    The chain and the Merkle root are both computed on the audited machine from
+    the audited file, so an attacker who can rewrite one can rewrite all of them.
+    A checkpoint is the escape: publish `(tree_size, root)` off-host and any later
+    edit below that size stops matching. This command produces the commitment;
+    where it goes is the operator's trust decision, not ours.
+    """
+    import json
+
+    from agentmetry.core.audit.trail_anchor import (
+        FileAnchorSink,
+        anchor_path,
+        build_checkpoint,
+        coverage_lines,
+        read_checkpoints,
+        verify_anchors,
+    )
+
+    path = Path(args.path)
+    if not path.is_file():
+        print(f"No such file: {path}")
+        return 1
+    anchors = Path(args.anchors) if args.anchors else anchor_path(path)
+
+    if args.show:
+        checkpoints = read_checkpoints(anchors)
+        if not checkpoints:
+            print(f"No checkpoints in {anchors}")
+            return 0
+        print(f"{len(checkpoints)} checkpoint(s) in {anchors}")
+        for cp in checkpoints:
+            print(f"  {cp.timestamp}  size {cp.tree_size:>7}  root {cp.root_sha256[:16]}…")
+        return 0
+
+    if args.verify:
+        coverage = verify_anchors(path, anchors)
+        for line in coverage_lines(coverage):
+            print(line.strip())
+        return 0 if coverage.ok else 1
+
+    try:
+        checkpoint = build_checkpoint(path, host_id=args.host_id or "")
+    except ValueError as exc:
+        print(str(exc))
+        return 1
+
+    # --print emits without recording. The point is to hand the statement to a
+    # sink we do not implement (a timestamp authority, a git commit, a log)
+    # without also implying it was anchored here.
+    if args.print_only:
+        print(checkpoint.statement() if not args.json else json.dumps(checkpoint.to_dict(), indent=2))
+        return 0
+
+    try:
+        receipt = FileAnchorSink(anchors).publish(checkpoint)
+    except (ValueError, OSError) as exc:
+        print(f"FAILED — {exc}")
+        return 1
+
+    print(f"Anchored {checkpoint.tree_size} record(s) at root {checkpoint.root_sha256}")
+    print(f"  checkpoint: {receipt.ref} in {anchors}")
+    print(f"  statement: {checkpoint.statement()}")
+    # Phrased as a condition, not an assertion. With --anchors the log may
+    # already be in a working copy of a protected remote, and telling an
+    # operator who has done the work that they have not is how a correct
+    # warning teaches people to ignore warnings.
+    print(
+        "  Until a copy of this log lives where this machine cannot write it, "
+        "the commitment can be rewritten along with the trail."
+    )
+    return 0
+
+
 def cmd_verify(args: argparse.Namespace) -> int:
     import json
 
@@ -689,6 +924,47 @@ def cmd_verify(args: argparse.Namespace) -> int:
                 # the file, so it is the more useful of the two to publish.
                 print(f"  merkle root: {root}")
                 print(f"  tree size: {size} (rfc6962-sha256)")
+
+            # Everything above was computed from the file being checked, which is
+            # the file an attacker with host access would have rewritten. Anchor
+            # coverage is the only part of this output that can contradict it, so
+            # it prints even when there are no anchors — an operator who never
+            # sees the sentence never learns the guarantee has a ceiling.
+            from agentmetry.core.audit.trail_anchor import coverage_lines, verify_anchors
+
+            # Which log this checks is what decides whether the check means
+            # anything. Beside the trail, an attacker who rewrote one rewrote
+            # the other. On a protected remote, the same comparison is the only
+            # thing here they could not forge.
+            from agentmetry.core.audit.trail_anchor import resolve_anchor_log
+
+            anchor_log, source = resolve_anchor_log(path, getattr(args, "anchors", None))
+            coverage = verify_anchors(path, anchor_log, local_only=(source == "default"))
+            for line in coverage_lines(coverage):
+                print(line)
+            if source == "config" and not anchor_log.is_file():
+                print(f"    AGENTMETRY_ANCHOR_LOG points at {anchor_log}, which does not exist")
+            if coverage.tampering:
+                # The chain printed OK several lines ago and it was telling the
+                # truth: the file is internally consistent, because whoever
+                # rewrote it made it so. Leaving that as the last word would let
+                # a skimmer take the wrong verdict away, so restate it.
+                print(
+                    "FAILED — the chain is internally consistent but contradicts a "
+                    "published anchor. The file was rewritten."
+                )
+                return 1
+            if not coverage.ok:
+                # Checkpoints exist and none of them cover this file. Worth
+                # failing, because an operator who configured an anchor log
+                # believes they are anchored. Not worth calling tampering:
+                # nothing here contradicts the trail, and a trust command that
+                # says "rewritten" about a clean file gets muted.
+                print(
+                    "FAILED — no checkpoint in this anchor log covers this trail. "
+                    "Check AGENTMETRY_ANCHOR_LOG, or anchor this file."
+                )
+                return 1
             return 0
         print(f"FAILED — {result.message}")
         if result.first_bad_line:
@@ -797,7 +1073,12 @@ def main(argv: list[str] | None = None) -> int:
     # platform. Same guard as scripts/demo.py.
     try:
         sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
-    except Exception:  # pragma: no cover - depends on the host console
+    except Exception:  # noqa: S110  # pragma: no cover - host console dependent
+        # The one swallow with nowhere to swallow into: this runs before logging
+        # is configured, and the failure means the console cannot render UTF-8,
+        # which is also why a log line about it would not render. The fallback is
+        # the console's own encoding, which is what would have happened without
+        # the call.
         pass
 
     parser = argparse.ArgumentParser(prog="agentmetry", description="Agentmetry local ops")
@@ -817,6 +1098,37 @@ def main(argv: list[str] | None = None) -> int:
     )
     serve.add_argument("--host", default="127.0.0.1")
     serve.add_argument("--port", type=int, default=8000)
+    hooks = sub.add_parser(
+        "hooks",
+        help="install IDE hook configs for the agents on this machine",
+    )
+    hooks.add_argument(
+        "action",
+        choices=("install", "status"),
+        help=(
+            "install writes hook configs; status reports coverage and exits "
+            "0 compliant, 1 needs remediation, 2 undeterminable"
+        ),
+    )
+    hooks.add_argument(
+        "--agent",
+        action="append",
+        default=[],
+        help="install only this agent (repeatable). Default: every supported agent present here",
+    )
+    hooks.add_argument(
+        "--all",
+        action="store_true",
+        help="install for every supported agent, present on this machine or not",
+    )
+
+    hook = sub.add_parser(
+        "hook",
+        help="forward one IDE hook event to ingest (see also the agentmetry-hook script)",
+    )
+    hook.add_argument("app", help="cursor | claude | codex | antigravity | qwen | kimi | qoder | codebuddy")
+    hook.add_argument("event", help="the IDE's event name, e.g. PreToolUse")
+
     sub.add_parser("status", help="orchestrator health and audit export status")
     stats = sub.add_parser("stats", help="audit trail metrics for dogfood (events, detections)")
     stats.add_argument("--days", type=int, default=7)
@@ -879,6 +1191,34 @@ def main(argv: list[str] | None = None) -> int:
         "--record-root", dest="record_root", action="store_true",
         help="recompute the root and store it in the chain sidecar",
     )
+    anchor = sub.add_parser(
+        "anchor",
+        help="publish a checkpoint committing the trail somewhere the host cannot rewrite",
+    )
+    anchor.add_argument("path", help="JSONL trail file")
+    anchor.add_argument(
+        "--anchors", default=None,
+        help="anchor log to append to (default: <trail>.anchors.jsonl)",
+    )
+    anchor.add_argument(
+        "--print", dest="print_only", action="store_true",
+        help="print the checkpoint statement without recording it, to hand to an external sink",
+    )
+    anchor.add_argument("--json", action="store_true", help="with --print: emit JSON, not one line")
+    anchor.add_argument("--show", action="store_true", help="list recorded checkpoints")
+    anchor.add_argument(
+        "--verify", action="store_true",
+        help="recompute each checkpoint's root from the trail and compare",
+    )
+    anchor.add_argument("--host-id", dest="host_id", default="", help="identity to stamp on the checkpoint")
+    mcp = sub.add_parser(
+        "mcp", help="list MCP servers configured for the agents on this machine"
+    )
+    mcp.add_argument("--project", default=None, help="project root to include (default: cwd)")
+    mcp.add_argument(
+        "--digest", action="store_true",
+        help="also print the config digest, which names no server and is safe to publish",
+    )
     verify = sub.add_parser("verify", help="verify evidence pack or JSONL trail chain")
     verify.add_argument(
         "path",
@@ -887,7 +1227,14 @@ def main(argv: list[str] | None = None) -> int:
     verify.add_argument(
         "--trail",
         action="store_true",
-        help="verify tamper-evident hash chain on an audit JSONL file",
+        help="verify the hash chain on an audit JSONL file and report anchor coverage",
+    )
+    verify.add_argument(
+        "--anchors",
+        default=None,
+        help="with --trail: check against this anchor log instead of the one beside "
+             "the trail. Point it at an off-host copy; a local one can be rewritten "
+             "by whoever rewrote the trail.",
     )
     doctor = sub.add_parser(
         "doctor", help="SIEM preflight (manifests, trail chain, health, hooks)"
@@ -922,6 +1269,8 @@ def main(argv: list[str] | None = None) -> int:
         "start": cmd_start,
         "serve": cmd_serve,
         "stop": cmd_stop,
+        "hooks": cmd_hooks,
+        "hook": cmd_hook,
         "status": cmd_status,
         "stats": cmd_stats,
         "logs": cmd_logs,
@@ -932,6 +1281,8 @@ def main(argv: list[str] | None = None) -> int:
         "export": cmd_export,
         "verify": cmd_verify,
         "prove": cmd_prove,
+        "anchor": cmd_anchor,
+        "mcp": cmd_mcp,
         "import-agt": cmd_import_agt,
         "doctor": cmd_doctor,
         "benchmark": cmd_benchmark,

{agentmetry-0.4.0 → agentmetry-0.6.0}/agentmetry/core/audit/adapters/agt.py

@@ -220,6 +220,8 @@ def agt_to_canonical(
     adds up to.
     """
     from agentmetry.core.audit.detection.traits import classify_command
+    from agentmetry.core.audit.atlas import attach_atlas
+    from agentmetry.core.audit.canonical import SCHEMA_VERSION
     from agentmetry.core.audit.mitre import get_mitre_mapping
 
     data = entry.get("data") if isinstance(entry.get("data"), dict) else {}
@@ -248,11 +250,12 @@ def agt_to_canonical(
     mapping = get_mitre_mapping(resource or "run", data or command)
     if mapping:
         tool["mitre"] = mapping
+    attach_atlas(tool)
 
     agent_did = str(entry.get("agent_did") or "")
 
     return {
-        "schema_version": "1.1.0",
+        "schema_version": SCHEMA_VERSION,
         # AGT's entry_id is `audit_<16 hex>`, not a UUID, so it cannot be used
         # as an event_id directly. Derived deterministically so re-importing the
         # same file does not mint new identities for the same events.