agentmetry 0.9.9__tar.gz → 0.10.0__tar.gz

{agentmetry-0.9.9 → agentmetry-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.9.9
+Version: 0.10.0
 Summary: Local-first endpoint sensor 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
@@ -44,19 +44,38 @@ Description-Content-Type: text/markdown
 
 A local-first endpoint sensor for AI coding agents.
 
-Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex and Antigravity,
-writes every tool call, approval and denial to a hash-chained JSONL trail on your
-machine, and runs sequence detection over the session. A credential read followed
-by network egress becomes one finding rather than two unremarkable log lines.
+Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex, GitHub Copilot,
+Antigravity, Qwen, Kimi, Qoder and CodeBuddy, writes every tool call, approval and
+denial to a hash-chained JSONL trail on your machine, and runs sequence detection
+over the session. A credential read followed by network egress becomes one finding
+rather than two unremarkable log lines. Findings carry MITRE ATT&CK labels, and
+MITRE ATLAS labels where ATLAS says something ATT&CK cannot.
 
-Everything runs locally. There are no cloud calls and no telemetry. Forwarding to
-Elastic ECS, Splunk HEC or a webhook exists and is off unless you configure it.
+Nothing leaves the machine unless you configure it, and there is no telemetry.
+Forwarding to Splunk HEC, Elastic ECS, Google SecOps, Microsoft Sentinel or a
+webhook (canonical JSON or CloudEvents) is off by default.
+
+## Try it with nothing installed
+
+```bash
+uvx agentmetry demo
+```
+
+It replays a session into a temporary directory it deletes: a private-key read,
+then an upload. That raises one critical finding. It then edits the trail and
+shows `agentmetry verify` fail.
+
+## Record a real agent
 
 ```bash
 pip install agentmetry
+agentmetry hooks install
+agentmetry start
 agentmetry doctor
 ```
 
+`agentmetry dashboard` opens the local console with a one-time sign-in link.
+
 ## Check the detection claims yourself
 
 The corpus ships inside the package, so this works from a clean install:
@@ -72,12 +91,19 @@ matters: any tool can fire on an attack, and a feed that cries wolf gets muted.
 ## What it does not do
 
 - **It is not a CASB.** It records the agents you wire in. An unmanaged browser
-  assistant is invisible to it.
-- **It is a recorder, not a sandbox.** The only enforcement path is pre-execution
-  DLP blocking in the hook.
+  assistant, or an IDE with its hooks off, is invisible to it.
+- **It is a recorder, not a sandbox.** By default it records. DLP and tool policy
+  can deny a call in the hook, before it runs, when you set them to block.
 - **The DLP is regex, not ML.** A starting pack you extend in YAML.
+- **macOS is in preview.** CI runs the full suite on Windows, Linux and macOS, but
+  only Windows and Linux are required checks, and no hook has been exercised
+  against a live agent on a Mac.
 - **It is a public alpha.** Integration surfaces may still change.
 
+For a fleet, a managed policy file can lock settings such as the DLP and tool
+policy modes so a developer cannot change them. See
+[docs/managed-policy.md](https://github.com/blitzcrieg1/agentmetry/blob/master/docs/managed-policy.md).
+
 Full documentation, the event schema, and the SIEM integration guides are in the
 repository.
 

agentmetry-0.10.0/README.md

@@ -0,0 +1,71 @@
+# Agentmetry
+
+A local-first endpoint sensor for AI coding agents.
+
+Agentmetry hooks the tool lifecycle of Claude Code, Cursor, Codex, GitHub Copilot,
+Antigravity, Qwen, Kimi, Qoder and CodeBuddy, writes every tool call, approval and
+denial to a hash-chained JSONL trail on your machine, and runs sequence detection
+over the session. A credential read followed by network egress becomes one finding
+rather than two unremarkable log lines. Findings carry MITRE ATT&CK labels, and
+MITRE ATLAS labels where ATLAS says something ATT&CK cannot.
+
+Nothing leaves the machine unless you configure it, and there is no telemetry.
+Forwarding to Splunk HEC, Elastic ECS, Google SecOps, Microsoft Sentinel or a
+webhook (canonical JSON or CloudEvents) is off by default.
+
+## Try it with nothing installed
+
+```bash
+uvx agentmetry demo
+```
+
+It replays a session into a temporary directory it deletes: a private-key read,
+then an upload. That raises one critical finding. It then edits the trail and
+shows `agentmetry verify` fail.
+
+## Record a real agent
+
+```bash
+pip install agentmetry
+agentmetry hooks install
+agentmetry start
+agentmetry doctor
+```
+
+`agentmetry dashboard` opens the local console with a one-time sign-in link.
+
+## Check the detection claims yourself
+
+The corpus ships inside the package, so this works from a clean install:
+
+```bash
+agentmetry benchmark
+```
+
+It replays recorded sessions through the real rule engine and exits non-zero on
+any missed rule or any false positive. The benign half is the number that
+matters: any tool can fire on an attack, and a feed that cries wolf gets muted.
+
+## What it does not do
+
+- **It is not a CASB.** It records the agents you wire in. An unmanaged browser
+  assistant, or an IDE with its hooks off, is invisible to it.
+- **It is a recorder, not a sandbox.** By default it records. DLP and tool policy
+  can deny a call in the hook, before it runs, when you set them to block.
+- **The DLP is regex, not ML.** A starting pack you extend in YAML.
+- **macOS is in preview.** CI runs the full suite on Windows, Linux and macOS, but
+  only Windows and Linux are required checks, and no hook has been exercised
+  against a live agent on a Mac.
+- **It is a public alpha.** Integration surfaces may still change.
+
+For a fleet, a managed policy file can lock settings such as the DLP and tool
+policy modes so a developer cannot change them. See
+[docs/managed-policy.md](https://github.com/blitzcrieg1/agentmetry/blob/master/docs/managed-policy.md).
+
+Full documentation, the event schema, and the SIEM integration guides are in the
+repository.
+
+- Source and issues: https://github.com/blitzcrieg1/agentmetry
+- Website: https://agentmetry.ai
+
+Apache-2.0.

{agentmetry-0.9.9 → agentmetry-0.10.0}/agentmetry/api/main.py

@@ -79,6 +79,22 @@ def _start_forwarders() -> list[asyncio.Task]:
     return tasks
 
 
+def antigravity_watcher_wanted() -> bool:
+    """Whether this recorder should tail the developer's Antigravity transcripts.
+
+    It used to start whenever the script existed, so every recorder did it,
+    including the dashboard demo, whose trail is supposed to hold seeded events
+    only. The watcher reads `~/.gemini/antigravity/brain`, the real one, so a
+    demo shown to someone could carry the presenter's actual agent activity, and
+    a second recorder doubled every Antigravity call. It now runs only where the
+    recorder accepts ingest, and `AGENTMETRY_ANTIGRAVITY_WATCHER=0` turns it off.
+    """
+    if not settings.audit_ingest_enabled:
+        return False
+    flag = os.environ.get("AGENTMETRY_ANTIGRAVITY_WATCHER", "").strip().lower()
+    return flag not in ("0", "false", "no", "off")
+
+
 def start_transcript_watcher(watcher_path: Path) -> subprocess.Popen:
     """Start the Antigravity transcript watcher, tied to this process's life.
 
@@ -111,6 +127,20 @@ def stop_transcript_watcher(process: subprocess.Popen) -> None:
 async def lifespan(app: FastAPI):
     from agentmetry.core.audit.migrate import backfill_db_from_jsonl
 
+    # The ingest-only token, which hooks prefer and the ingest route accepts.
+    # Without it a hook running as another account (Codex's Windows sandbox)
+    # could not authenticate and every event it sent was lost (#302). Owner-
+    # only like the full token; `hooks install` widens it to Codex's sandbox
+    # accounts where they exist. A failure here costs that, never the boot.
+    from agentmetry.core import api_token
+    from agentmetry.core.auth import auth_is_disabled
+
+    if not auth_is_disabled():
+        try:
+            api_token.ensure_ingest_token()
+        except OSError:
+            logger.exception("Could not write the ingest-only token; hooks fall back to the full token")
+
     # Backfill SQLite from the existing JSONL trail. A broken or locked audit DB
     # must degrade the dashboard, never stop the daemon from booting: the
     # recorder's job is to keep recording.
@@ -211,7 +241,7 @@ async def lifespan(app: FastAPI):
     watcher_process = None
     try:
         watcher_path = Path(__file__).resolve().parents[4] / "scripts" / "antigravity_transcript_watcher.py"
-        if watcher_path.exists():
+        if watcher_path.exists() and antigravity_watcher_wanted():
             watcher_process = start_transcript_watcher(watcher_path)
             logger.info("Started Antigravity transcript watcher (PID: %s)", watcher_process.pid)
     except Exception as exc:
@@ -306,7 +336,24 @@ def mount_dashboard(target: FastAPI, directory: Path = _DASHBOARD_DIR) -> bool:
 
     from fastapi.staticfiles import StaticFiles
 
-    target.mount("/", StaticFiles(directory=str(directory), html=True), name="dashboard")
+    class DashboardFiles(StaticFiles):
+        """The export, with its HTML pages marked `no-cache`.
+
+        Served with no cache header at all, a browser may reuse a stale page on
+        an ordinary reload, and the page names the old scripts, so an upgraded
+        recorder kept showing the previous dashboard until a hard reload.
+        `no-cache` still lets the browser keep a copy; it only has to ask
+        whether the page changed. The scripts are not touched: their names
+        change with every build.
+        """
+
+        async def get_response(self, path: str, scope):  # type: ignore[override]
+            response = await super().get_response(path, scope)
+            if response.headers.get("content-type", "").startswith("text/html"):
+                response.headers["Cache-Control"] = "no-cache"
+            return response
+
+    target.mount("/", DashboardFiles(directory=str(directory), html=True), name="dashboard")
     logger.info("Serving dashboard from %s", directory)
     return True
 

{agentmetry-0.9.9 → agentmetry-0.10.0}/agentmetry/api/routes/audit.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import logging
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Literal
@@ -11,12 +12,13 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import FileResponse
 from pydantic import BaseModel, Field, field_validator
 
-from agentmetry.core.auth import require_api_key
+from agentmetry.core.auth import require_api_key, require_ingest_key
 from agentmetry.core.audit.detection.disposition import STATUSES, get_disposition_store
 from agentmetry.core.audit.ingest import ingest_external_event
 from agentmetry.core.config import settings
 
 router = APIRouter(prefix="/audit", tags=["audit"])
+logger = logging.getLogger(__name__)
 
 _RUN_ACTION_TYPES = frozenset({
     "session_start",
@@ -142,6 +144,8 @@ class ExternalIngestBody(BaseModel):
     # drops what it does not know, silently, which has already cost this file
     # two shipped bugs.
     schema_concealed: dict[str, int] = Field(default_factory=dict)
+    # Model-steering text in a tool description (#188), counts per category.
+    schema_injection: dict[str, int] = Field(default_factory=dict)
     server_version: str = ""
     list_changed: bool | None = None
 
@@ -191,7 +195,24 @@ def _event_source_app(event: dict[str, Any]) -> str:
     return "agentmetry"
 
 
-@router.post("/ingest", dependencies=[Depends(require_api_key)])
+_THROTTLE_WARNED: dict[str, float] = {}
+
+
+def _warn_throttled(source_app: str) -> None:
+    """Log throttling once a minute per source, so a flood does not flood the log too."""
+    import time
+
+    now = time.monotonic()
+    if now - _THROTTLE_WARNED.get(source_app, -60.0) >= 60.0:
+        _THROTTLE_WARNED[source_app] = now
+        # The caller passes a resolved, allowlisted name, so this changes
+        # nothing today. It keeps a future caller that passes client text from
+        # forging log lines, and it is the guard code scanning can see.
+        safe = (source_app or "unknown").replace("\r", "").replace("\n", "")
+        logger.warning("Ingest rate limit reached for source %s; events are spooled for replay", safe)
+
+
+@router.post("/ingest", dependencies=[Depends(require_ingest_key)])
 async def audit_ingest(body: ExternalIngestBody):
     """Accept canonical adapter events from Cursor, Claude, MCP proxy, etc."""
     if not settings.audit_ingest_enabled:
@@ -199,6 +220,26 @@ async def audit_ingest(body: ExternalIngestBody):
     if not settings.audit_export_enabled:
         raise HTTPException(status_code=503, detail="Audit export is disabled")
 
+    # Rate limit per source app and per session (#312). The hook spools a 429
+    # and the recorder's drain replays it with the original timestamps, so a
+    # burst past the cap is late, not lost.
+    from agentmetry.core.audit.external import _resolve_source_app
+    from agentmetry.core.audit.ingest_quota import get_limiter
+
+    # Keyed and logged by the name the trail will record, not the one the
+    # client sent: an unlisted name becomes `unknown`. Keyed on raw text, a
+    # flood inventing a name per event got a fresh bucket each time, and the
+    # warning wrote client text into the log.
+    source = _resolve_source_app(body.source_app)[0]
+    limiter = get_limiter()
+    if not limiter.allow(source, body.session_id or body.correlation_id):
+        _warn_throttled(source)
+        raise HTTPException(
+            status_code=429,
+            detail="Ingest rate limit reached; the hook spools this event and the recorder replays it",
+            headers={"Retry-After": str(limiter.retry_after())},
+        )
+
     payload = body.model_dump(exclude_none=True)
     try:
         canonical = await ingest_external_event(payload)
@@ -495,11 +536,19 @@ async def audit_status():
     Powers the freshness badge and `selftest` — makes silent hook failure visible
     instead of the operator falsely believing they are being audited.
     """
+    from agentmetry.core.audit.ingest_quota import get_limiter
     from agentmetry.core.audit.spool import spool_depth, spool_oldest_age_seconds
     from agentmetry.core.audit.trail_db import get_trail_db
     path = Path(settings.audit_export_path)
     if not settings.audit_export_enabled:
-        return {"enabled": False, "last_event_utc": None, "recent": 0, "by_source": {}, "path": str(path)}
+        return {
+            "enabled": False,
+            "last_event_utc": None,
+            "recent": 0,
+            "by_source": {},
+            "path": str(path),
+            "demo": settings.demo_mode,
+        }
 
     status_data = get_trail_db().status()
     # Pending spool depth belongs in the same payload as freshness. A feed that
@@ -516,6 +565,12 @@ async def audit_status():
         # Per SIEM: the last seq it accepted, and how long it has been failing.
         "forwarding": _forward_status(),
         "spool_oldest_age_seconds": spool_oldest_age_seconds(),
+        # Events refused by the ingest rate limit since the recorder started.
+        # They went to the hook spool, so a non-zero count is late work, and a
+        # growing one is an agent sending far faster than agents do (#312).
+        "ingest_throttled": get_limiter().snapshot(),
+        # A demo server's events are synthetic. The dashboard says so from here.
+        "demo": settings.demo_mode,
     }
 
 

{agentmetry-0.9.9 → agentmetry-0.10.0}/agentmetry/cli/__init__.py

@@ -628,7 +628,14 @@ def cmd_cloud(args: argparse.Namespace) -> int:
         headers = {"Content-Type": "application/json"}
         if key:
             headers["Authorization"] = f"Bearer {key}"
-        resp = httpx.post(f"{url}/api/v1/audit/ingest", json=payload, headers=headers, timeout=15)
+        # A 429 is the ingest rate limit (#312). Unlike a hook, this importer
+        # has no spool, so it waits as told and tries again rather than drop
+        # the event.
+        for _ in range(6):
+            resp = httpx.post(f"{url}/api/v1/audit/ingest", json=payload, headers=headers, timeout=15)
+            if resp.status_code != 429:
+                break
+            time.sleep(min(30.0, float(resp.headers.get("Retry-After", "1") or 1)))
         ok = resp.status_code < 300
         if ok:
             posted += 1
@@ -1139,6 +1146,32 @@ def cmd_mcp(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_scan(args: argparse.Namespace) -> int:
+    """Check what an agent is about to depend on: MCP servers, skills, packages.
+
+    Exits 1 when anything is found and 2 when nothing could be read. Unlike
+    `mcp` and `posture`, which a health check runs in the background, this is
+    run on purpose before something is installed, so a finding should stop the
+    script that ran it. See core/scanner/scan.py.
+    """
+    import json as _json
+    from pathlib import Path as _Path
+
+    from agentmetry.core.scanner.scan import run
+
+    report = run(
+        args.target,
+        project=_Path(args.project).resolve() if args.project else _Path.cwd(),
+        known_file=args.known,
+    )
+    if args.json:
+        print(_json.dumps(report.to_json(), indent=2))
+    else:
+        for line in report.lines():
+            print(line)
+    return report.exit_code()
+
+
 def cmd_posture(args: argparse.Namespace) -> int:
     """Report agent settings that take a human or a hook out of the loop.
 
@@ -1698,6 +1731,18 @@ def main(argv: list[str] | None = None) -> int:
     posture.add_argument(
         "--strict", action="store_true", help="exit 1 when any high-severity finding is present",
     )
+    scan = sub.add_parser(
+        "scan",
+        help="check MCP servers, skills or a package name before an agent depends on them",
+    )
+    scan.add_argument(
+        "target", nargs="?", default=None,
+        help="a file or folder (skills, rules, a saved tools/list), npm:NAME or pypi:NAME; "
+        "omit to scan the MCP servers configured on this machine",
+    )
+    scan.add_argument("--project", default=None, help="project root whose MCP config to include (default: cwd)")
+    scan.add_argument("--known", default=None, help="file of extra known package names, one per line (npm:/pypi: or bare)")
+    scan.add_argument("--json", action="store_true", help="print the report as JSON")
     otel = sub.add_parser(
         "otel", help="receive Claude Code's native OpenTelemetry stream (no hooks needed)"
     )
@@ -1810,6 +1855,7 @@ def main(argv: list[str] | None = None) -> int:
         "anchor": cmd_anchor,
         "mcp": cmd_mcp,
         "posture": cmd_posture,
+        "scan": cmd_scan,
         "dashboard": cmd_dashboard,
         "otel": cmd_otel,
         "import-agt": cmd_import_agt,

{agentmetry-0.9.9 → agentmetry-0.10.0}/agentmetry/core/api_token.py

@@ -155,6 +155,82 @@ def write_ingest_token(token: str, path: Path | None = None) -> Path:
     return target
 
 
+def ensure_ingest_token(path: Path | None = None) -> str:
+    """The ingest-only token, creating it once if it does not exist yet.
+
+    The core used to leave this to Agentmetry Enterprise, which left the open
+    source install with one credential that could do everything. A hook that
+    runs as another account (Codex's Windows sandbox runs hooks as its own local
+    user) then had two choices: be handed the full key, which also reads the
+    trail and closes detections, or record nothing. It recorded nothing, and
+    nothing said so (#302). An existing token, Enterprise's included, is kept.
+    """
+    target = path or ingest_token_path()
+    existing = read_token(target)
+    if existing:
+        return existing
+    return read_token(write_ingest_token(secrets.token_urlsafe(32), target))
+
+
+#: The local accounts Codex's Windows sandbox runs commands and hooks as.
+CODEX_SANDBOX_ACCOUNTS = ("CodexSandboxOffline", "CodexSandboxOnline")
+
+
+def codex_sandbox_accounts() -> list[str]:
+    """Which of Codex's sandbox accounts exist on this Windows machine."""
+    if os.name != "nt":
+        return []
+    import subprocess  # account lookup only; the hook never calls this
+    found = []
+    for name in CODEX_SANDBOX_ACCOUNTS:
+        try:
+            probe = subprocess.run(["net", "user", name], capture_output=True, check=False, timeout=15)
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if probe.returncode == 0:
+            found.append(name)
+    return found
+
+
+def grant_read(path: Path, accounts: list[str]) -> list[str]:
+    """Add a read entry for each account to the file's ACL. Windows only.
+
+    Only ever called on the ingest-only token: what an account gains is the
+    ability to send events, never to read the trail or close a detection.
+    """
+    if os.name != "nt" or not accounts:
+        return []
+    import subprocess  # ACL work only; the hook reads tokens on every call
+    granted = []
+    for name in accounts:
+        try:
+            done = subprocess.run(
+                ["icacls", str(path), "/grant", f"{name}:R"],
+                capture_output=True, check=False, timeout=15,
+            )
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if done.returncode == 0:
+            granted.append(name)
+    return granted
+
+
+def readable_by(path: Path, accounts: list[str]) -> list[str] | None:
+    """Which of these accounts hold an entry on the file's ACL, or None if it cannot be told."""
+    if os.name != "nt":
+        return None
+    import subprocess  # ACL work only; the hook reads tokens on every call
+    try:
+        out = subprocess.run(
+            ["icacls", str(path)], capture_output=True, text=True, check=False, timeout=15
+        ).stdout.lower()
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if not out:
+        return None
+    return [name for name in accounts if f"\\{name.lower()}:" in out or f" {name.lower()}:" in out]
+
+
 def auth_disabled() -> bool:
     return os.environ.get("AGENTMETRY_AUTH_DISABLED", "").strip().lower() in _TRUTHY
 

{agentmetry-0.9.9 → agentmetry-0.10.0}/agentmetry/core/audit/heartbeat.py

@@ -56,6 +56,7 @@ from __future__ import annotations
 import logging
 import os
 import uuid
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
@@ -98,10 +99,30 @@ def _hook_facts() -> dict[str, Any]:
         "hook_coverage": states,
         "hooks_uncovered": hook_coverage.uncovered(states),
         "hooks_unverified": hook_coverage.unverified(states),
+        "hooks_silent": _silent_agents(states),
         "hook_profile": hook_coverage.attestation_profile(),
     }
 
 
+def _silent_agents(states: dict[str, str]) -> list[str]:
+    """Configured agents with no event in the observed window (#300).
+
+    Its own field, not a reason to degrade: an agent nobody used is silent too,
+    and a beat that degrades for that trains a fleet to ignore it. A SIEM can
+    alert on `heartbeat.hooks_silent` where silence is not expected. An index
+    that cannot be read reports nothing rather than break the beat.
+    """
+    from agentmetry.core.audit.trail_db import get_trail_db
+    from agentmetry.core.diagnostics import hook_coverage
+
+    try:
+        last_seen = get_trail_db().last_event_by_source()
+    except Exception:  # noqa: BLE001 - the beat must go out regardless
+        logger.debug("heartbeat: could not read last event per source", exc_info=True)
+        return []
+    return hook_coverage.silent(states, last_seen, datetime.now(timezone.utc))
+
+
 def _policy_facts() -> dict[str, Any]:
     """What a managed policy locks here, and which managed sources were refused.
 
@@ -270,6 +291,15 @@ def build_heartbeat_event(now_utc: str, root: tuple[str, int] | None = None) ->
         # Never coverage, never silent. Codex went missing from the attestation
         # for exactly as long as nothing said its name.
         reason += f" (unverifiable: {', '.join(facts['hooks_unverified'])})"
+    if facts.get("hooks_silent") and not service_profile:
+        # Configured is not recorded. Named here so a person reading the beat
+        # sees it; kept out of `degraded` because an unused agent is silent too.
+        from agentmetry.core.diagnostics.hook_coverage import OBSERVED_WINDOW_DAYS
+
+        reason += (
+            f" (configured but not observed in {OBSERVED_WINDOW_DAYS} days: "
+            f"{', '.join(facts['hooks_silent'])})"
+        )
 
     return {
         "schema_version": SCHEMA_VERSION,