agentmetry 0.9.8__tar.gz → 0.10.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agentmetry
-Version: 0.9.8
-Summary: Local-first flight recorder for AI coding agents: hash-chained audit trail, MITRE-mapped sequence detection, DLP
+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
 Project-URL: Issues, https://github.com/blitzcrieg1/agentmetry/issues
@@ -37,26 +37,45 @@ 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.10; extra == 'dev'
+Requires-Dist: ruff==0.17.1; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Agentmetry
 
-A local-first flight recorder for AI coding agents.
+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.8 → 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.8 → 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",
@@ -105,7 +107,7 @@ class ExternalIngestBody(BaseModel):
     )
     event_type: str = Field(
         ...,
-        description="session_start | session_end | tool_called | tool_denied | tool_failed | approval_request | approval_response | mcp_schema",
+        description="session_start | session_end | tool_called | tool_denied | tool_failed | approval_request | approval_response | mcp_schema | hook_remediation",
     )
     correlation_id: str = ""
     session_id: str = ""
@@ -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.8 → agentmetry-0.10.0}/agentmetry/cli/__init__.py

@@ -48,6 +48,70 @@ def _api_base_url(port: int) -> str:
     return os.environ.get("AGENTMETRY_URL", "").strip().rstrip("/") or _base_url(port)
 
 
+def _add_dir_flags(parser: argparse.ArgumentParser) -> None:
+    """The path split. Omit the flags and nothing moves.
+
+    `SUPPRESS`, so the same flag on `agentmetry` and on the subcommand do not
+    overwrite each other with a default of None.
+    """
+    parser.add_argument(
+        "--data-dir", default=argparse.SUPPRESS,
+        help="trail, spool, token and logs (env AGENTMETRY_DATA_DIR)",
+    )
+    parser.add_argument(
+        "--user-profile-dir", default=argparse.SUPPRESS,
+        help="the developer home whose IDE configs to install into and check "
+        "(env AGENTMETRY_USER_PROFILE_DIR); for a recorder run as root or LocalSystem",
+    )
+    parser.add_argument(
+        "--policy-dir", default=argparse.SUPPRESS,
+        help="an extra managed policy location, checked like the platform one "
+        "(env AGENTMETRY_POLICY_DIR)",
+    )
+
+
+def _apply_dir_flags(args: argparse.Namespace) -> None:
+    """Export the path flags before a command reads data_dir() or the profile.
+
+    Exported, not passed: `start` spawns `serve`, and the hook commands it
+    writes run in other processes, all of which read the environment.
+    """
+    global _DATA_DIR, _PID_FILE
+    if getattr(args, "user_profile_dir", None):
+        os.environ["AGENTMETRY_USER_PROFILE_DIR"] = args.user_profile_dir
+    if getattr(args, "policy_dir", None):
+        os.environ["AGENTMETRY_POLICY_DIR"] = args.policy_dir
+    if getattr(args, "data_dir", None):
+        os.environ["AGENTMETRY_DATA_DIR"] = args.data_dir
+        # Only when the flag was given: a caller that already pointed these at
+        # a temp tree must not have them recomputed under it.
+        _DATA_DIR = data_dir()
+        _PID_FILE = _DATA_DIR / "agentmetry.pid"
+
+
+def _apply_managed_policy(args: argparse.Namespace) -> None:
+    """Locks over flags and environment, for this process and everything it starts.
+
+    After `_apply_dir_flags`, so `--data-dir` cannot move a trail a fleet
+    locked. Says so when it overrides a flag: a silently ignored flag reads as
+    a bug.
+    """
+    global _DATA_DIR, _PID_FILE
+    from agentmetry.core import managed_policy
+
+    try:
+        policy = managed_policy.apply_locks()
+    except Exception as exc:
+        print(f"Managed policy was not applied: {exc}", file=sys.stderr)
+        return
+    if "data_dir" not in policy.locked:
+        return
+    if getattr(args, "data_dir", None):
+        print("--data-dir ignored: managed policy locks data_dir.", file=sys.stderr)
+    _DATA_DIR = data_dir()
+    _PID_FILE = _DATA_DIR / "agentmetry.pid"
+
+
 def _api_headers() -> dict[str, str]:
     from agentmetry.core.api_token import client_token
 
@@ -564,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
@@ -636,11 +707,12 @@ def _hooks_status() -> int:
     """
     from agentmetry.core.diagnostics import hook_coverage
 
-    if hook_coverage.is_service_profile():
+    if hook_coverage.profile_blind():
         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.",
+            "Run this in the user's context, or name the developer's home with "
+            "--user-profile-dir.",
             file=sys.stderr,
         )
         return 2
@@ -1074,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.
 
@@ -1414,10 +1512,10 @@ def cmd_demo(args: argparse.Namespace) -> int:
 def cmd_doctor(args: argparse.Namespace) -> int:
     """SIEM preflight: manifests, trail chain, orchestrator health, hooks."""
     sys.path.insert(0, str(_ORCH_ROOT))
-    from agentmetry.core.diagnostics.doctor import format_report, run_doctor
+    from agentmetry.core.diagnostics.doctor import print_report, run_doctor
 
     report = run_doctor(fix_drivers=getattr(args, "fix", False))
-    print("Agentmetry doctor\n" + format_report(report))
+    print_report(report, as_json=getattr(args, "json", False))
     return report.exit_code
 
 
@@ -1451,6 +1549,7 @@ def main(argv: list[str] | None = None) -> int:
         prog="agentmetry",
         description="Agentmetry local ops. New here? Start with `agentmetry demo`.",
     )
+    _add_dir_flags(parser)
     parser.add_argument("--port", type=int, default=8000)
     sub = parser.add_subparsers(dest="command", required=True)
     # First, so it heads the help: it is the one command that needs nothing set up.
@@ -1465,6 +1564,7 @@ def main(argv: list[str] | None = None) -> int:
 
     sub.add_parser("stop", help="stop the orchestrator")
     start = sub.add_parser("start", help="start the orchestrator (detached)")
+    _add_dir_flags(start)
     start.add_argument(
         "--host",
         default="127.0.0.1",
@@ -1474,12 +1574,14 @@ def main(argv: list[str] | None = None) -> int:
         "serve",
         help="run the orchestrator in the foreground (what autostart registers)",
     )
+    _add_dir_flags(serve)
     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",
     )
+    _add_dir_flags(hooks)
     hooks.add_argument(
         "action",
         choices=("install", "status"),
@@ -1629,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)"
     )
@@ -1681,6 +1795,13 @@ def main(argv: list[str] | None = None) -> int:
     doctor = sub.add_parser(
         "doctor", help="SIEM preflight (manifests, trail chain, health, hooks)"
     )
+    _add_dir_flags(doctor)
+    doctor.add_argument(
+        "--json",
+        action="store_true",
+        help="the report as JSON, for a deployment script: exit_code, "
+        "orchestrator_reachable, hooks, policy and findings",
+    )
     doctor.add_argument(
         "--fix",
         action="store_true",
@@ -1708,6 +1829,8 @@ def main(argv: list[str] | None = None) -> int:
     replay.add_argument("--trail", default="", help="trail to read (default: the configured trail)")
 
     args = parser.parse_args(argv)
+    _apply_dir_flags(args)
+    _apply_managed_policy(args)
     handlers = {
         "demo": cmd_demo,
         "start": cmd_start,
@@ -1732,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.8 → 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