agentmetry 0.4.0__py3-none-any.whl

agentmetry/core/audit/policy.py

@@ -0,0 +1,99 @@
+"""Local policy checks for agent tool calls.
+
+**This is not OPA.** It is a small built-in ruleset. Real OPA/Rego evaluation is
+on the roadmap; `agentmetry/policies/opa/agent_rules.rego` is a draft for that work and is
+NOT evaluated by this module.
+
+Two design rules, both learned the hard way:
+
+1. **Annotate, never rewrite.** A policy verdict is a separate fact from what
+   actually happened. The previous version set `action.outcome = "denied"` on
+   events that had *already executed* on the agent's machine, which put a lie in
+   the audit trail: an incident responder would read "denied" for a tool that
+   ran. It also blinded every detection rule that keys on `outcome == "success"`
+   (a burst of `shell.rm` stopped firing `destructive-delete-burst` precisely
+   because policy flagged it). The verdict now lands in its own `policy` block
+   and `action` is left alone.
+
+2. **This cannot block.** By the time an event reaches the ingest API the tool
+   has already run. Real prevention has to happen in the hook process,
+   pre-execution, the way DLP `block` mode does. The annotation records
+   `enforced: false` so nobody mistakes it for enforcement.
+
+Off by default (`AGENTMETRY_POLICY_ENABLED=1` to turn on): the ruleset below is
+a hardcoded starting point, not something to impose on every operator.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class PolicyVerdict:
+    allowed: bool
+    rule_id: str = ""
+    reason: str = ""
+
+
+def _norm(name: str) -> str:
+    """Fold a tool name the same way core.audit.mitre does.
+
+    Exact string matching on `tool.qualified` was trivially evadable: a rule for
+    "shell.rm" missed "shell.RM" and "shell_rm". Normalizing at least closes the
+    spelling gap. It does NOT close the real gap (see module docstring): a shell
+    tool running `rm -rf` under any name is still not caught here.
+    """
+    return name.lower().replace("_", "").replace("-", "")
+
+
+# Tools that should not run unattended. Deliberately tiny: this is a default,
+# not a policy language. The roadmap replaces it with real Rego.
+_RESTRICTED: dict[str, str] = {
+    _norm("kubectl.exec"): "restricted:kubectl-exec",
+    _norm("aws.iam.delete_user"): "restricted:iam-delete-user",
+    _norm("shell.rm"): "restricted:shell-rm",
+}
+
+
+def evaluate_policy(event: dict[str, Any]) -> PolicyVerdict:
+    """Return a verdict for one canonical event. Never mutates the event."""
+    tool = event.get("tool")
+    qualified = str(tool.get("qualified") or "") if isinstance(tool, dict) else ""
+    if not qualified:
+        return PolicyVerdict(allowed=True)
+
+    rule_id = _RESTRICTED.get(_norm(qualified))
+    if rule_id is None:
+        return PolicyVerdict(allowed=True)
+
+    # A restricted tool is allowed when a human explicitly approved this action.
+    action = event.get("action") or {}
+    if action.get("type") == "approval_response" and action.get("outcome") == "success":
+        return PolicyVerdict(allowed=True)
+
+    return PolicyVerdict(
+        allowed=False,
+        rule_id=rule_id,
+        reason=f"{qualified} is restricted and had no recorded human approval",
+    )
+
+
+def annotate(event: dict[str, Any]) -> None:
+    """Attach a policy verdict to `event['policy']`, in place.
+
+    Only writes when the verdict is a denial, and only ever touches the `policy`
+    key. `action.outcome` stays whatever actually happened.
+    """
+    verdict = evaluate_policy(event)
+    if verdict.allowed:
+        return
+    event["policy"] = {
+        "decision": "deny",
+        "rule_id": verdict.rule_id,
+        "engine": "builtin",
+        # This event already executed. We observed it; we did not stop it.
+        "enforced": False,
+        "reason": verdict.reason,
+    }

agentmetry/core/audit/redaction.py

@@ -0,0 +1,50 @@
+"""Secret scrubbing for captured command text (Tier A/B).
+
+When command logging is enabled, the raw command string can contain inline
+secrets (bearer tokens, basic-auth URLs, --password values, cloud keys) that
+key-based argument redaction never sees. Scrub those before storage.
+
+Keep the pattern list in sync with the inline mirror in
+`scripts/agentmetry_ingest.py` (the standalone hook cannot import this module).
+"""
+
+from __future__ import annotations
+
+import re
+
+_SECRET_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(r"(?i)(bearer\s+)[A-Za-z0-9._\-]+"), r"\1<redacted>"),
+    (re.compile(r"(?i)(authorization:\s*)\S+"), r"\1<redacted>"),
+    # user:pass@host in URLs
+    (re.compile(r"(https?://)[^/\s:@]+:[^/\s@]+@"), r"\1<redacted>@"),
+    # --password X / --token=X / -p X
+    (re.compile(r"(?i)(-{1,2}(?:password|token|secret|api[-_]?key|pwd)[=\s]+)\S+"), r"\1<redacted>"),
+    # key=value / key: value assignments
+    (
+        re.compile(
+            r"(?i)\b(password|passwd|pwd|token|secret|api[-_]?key|apikey|access[-_]?key)\s*[=:]\s*[^\s;&|\"']+"
+        ),
+        r"\1=<redacted>",
+    ),
+    (re.compile(r"\bAKIA[0-9A-Z]{16}\b"), "<redacted-aws-key>"),
+    (re.compile(r"\bsk-[A-Za-z0-9]{20,}\b"), "<redacted-key>"),
+    (re.compile(r"\bgh[pousr]_[A-Za-z0-9]{20,}\b"), "<redacted-gh-token>"),
+    (re.compile(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b"), "<redacted-slack-token>"),
+]
+
+
+def scrub_secrets(text: str) -> str:
+    """Mask obvious inline secrets in a command/string. Best-effort, conservative."""
+    if not isinstance(text, str) or not text:
+        return text
+    out = text
+    for pattern, repl in _SECRET_PATTERNS:
+        out = pattern.sub(repl, out)
+    return out
+
+
+def scrub_arg_values(args: object) -> object:
+    """Scrub secret patterns inside string values of an arguments dict."""
+    if not isinstance(args, dict):
+        return args
+    return {k: (scrub_secrets(v) if isinstance(v, str) else v) for k, v in args.items()}

agentmetry/core/audit/replay.py

@@ -0,0 +1,54 @@
+"""ASCII timeline rendering for `agentmetry replay`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentmetry.core.audit.canonical import normalize_outbox_row
+
+_ICONS = {
+    "session_start": "▶",
+    "session_end": "■",
+    "approval_request": "⏸",
+    "approval_response": "✓",
+    "tool_called": "🔧",
+    "config_change": "⚙",
+}
+
+
+def format_timeline(rows: list[dict[str, Any]], *, thread_id: str) -> str:
+    if not rows:
+        return f"No audit events for thread_id={thread_id}"
+
+    lines = [f"Agentmetry replay — correlation_id={thread_id}", f"{'─' * 60}"]
+
+    for row in rows:
+        canonical = normalize_outbox_row(row)
+        if canonical is None:
+            ts = row.get("ts", "?")
+            topic = row.get("topic", "?")
+            lines.append(f"  {ts}  [{topic}]")
+            continue
+
+        ts = canonical["timestamp_utc"][:19].replace("T", " ")
+        action = canonical["action"]
+        icon = _ICONS.get(action["type"], "·")
+        outcome = action["outcome"]
+        label = action["type"]
+
+        detail_parts: list[str] = []
+        if skill := canonical.get("agent", {}).get("skill_id"):
+            detail_parts.append(f"skill={skill}")
+        if tool := canonical.get("tool"):
+            detail_parts.append(f"tool={tool.get('qualified') or tool.get('name')}")
+            if outcome == "denied" and action.get("reason"):
+                detail_parts.append(f"reason={action['reason']}")
+        if action.get("reason") and action["type"] == "approval_response":
+            detail_parts.append(action["reason"])
+
+        detail = f"  ({', '.join(detail_parts)})" if detail_parts else ""
+        lines.append(f"  {ts}  {icon} {label}/{outcome}{detail}  seq={canonical.get('seq')}")
+
+    lines.append(f"{'─' * 60}")
+    lines.append(f"{len(rows)} event(s)")
+    return "\n".join(lines)

agentmetry/core/audit/run_context.py

@@ -0,0 +1,129 @@
+"""Per-run audit context — initiator provenance and last gated tool (schema v1.1)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agentmetry.core.config import settings
+
+# thread_id → initiator block (set at run start, server-derived only)
+_thread_initiators: dict[str, dict[str, str]] = {}
+# thread_id → last successful tool call on this run (for approval binding)
+_thread_last_tool: dict[str, dict[str, str]] = {}
+
+
+def _operator_id() -> str:
+    return settings.operator_id.strip() or "local"
+
+
+def build_initiator(triggered_by: str) -> dict[str, str]:
+    """Derive initiator from run origin. Must never trust client-supplied headers."""
+    operator_id = _operator_id()
+    if triggered_by == "manual":
+        return {"actor_type": "human", "trigger": "manual", "operator_id": operator_id}
+    if triggered_by.startswith("channel:"):
+        return {"actor_type": "human", "trigger": "channel", "operator_id": operator_id}
+    if triggered_by == "cron":
+        return {"actor_type": "autonomous", "trigger": "cron", "operator_id": operator_id}
+    if triggered_by == "vault_watch":
+        return {"actor_type": "autonomous", "trigger": "vault_watch", "operator_id": operator_id}
+    if triggered_by == "ingress":
+        return {"actor_type": "autonomous", "trigger": "ingress", "operator_id": operator_id}
+    if triggered_by == "recovery":
+        return {"actor_type": "autonomous", "trigger": "recovery", "operator_id": operator_id}
+    return {
+        "actor_type": "autonomous",
+        "trigger": triggered_by,
+        "operator_id": operator_id,
+    }
+
+
+def actor_from_initiator(initiator: dict[str, str]) -> dict[str, str]:
+    human = initiator.get("actor_type") == "human"
+    return {
+        "type": "user" if human else "agent",
+        "id": initiator.get("operator_id") or _operator_id(),
+        "role": "operator",
+    }
+
+
+def default_initiator() -> dict[str, str]:
+    return build_initiator("manual")
+
+
+def set_thread_initiator(thread_id: str, triggered_by: str) -> dict[str, str]:
+    initiator = build_initiator(triggered_by)
+    _thread_initiators[thread_id] = initiator
+    return initiator
+
+
+def get_thread_initiator(thread_id: str) -> dict[str, str] | None:
+    return _thread_initiators.get(thread_id)
+
+
+def resolve_initiator(
+    payload: dict[str, Any], thread_id: str = ""
+) -> dict[str, str]:
+    """Read initiator from payload or thread cache; fallback manual human."""
+    raw = payload.get("initiator")
+    if isinstance(raw, dict) and raw.get("actor_type"):
+        return {
+            "actor_type": str(raw.get("actor_type") or "human"),
+            "trigger": str(raw.get("trigger") or "manual"),
+            "operator_id": str(raw.get("operator_id") or _operator_id()),
+        }
+    triggered_by = str(payload.get("triggered_by") or "")
+    if triggered_by:
+        return build_initiator(triggered_by)
+    if thread_id:
+        cached = _thread_initiators.get(thread_id)
+        if cached:
+            return cached
+    return default_initiator()
+
+
+def record_tool_call(thread_id: str, qualified: str, arguments_sha256: str) -> None:
+    if not thread_id:
+        return
+    server = qualified.split(".", 1)[0] if "." in qualified else ""
+    _thread_last_tool[thread_id] = {
+        "tool": qualified,
+        "server": server,
+        "input_hash": arguments_sha256,
+    }
+
+
+def last_gated_action(thread_id: str) -> dict[str, str] | None:
+    if not thread_id:
+        return None
+    action = _thread_last_tool.get(thread_id)
+    if not action or not action.get("tool"):
+        return None
+    return dict(action)
+
+
+def clear_run_context(thread_id: str) -> None:
+    _thread_initiators.pop(thread_id, None)
+    _thread_last_tool.pop(thread_id, None)
+
+
+def audit_payload(
+    thread_id: str,
+    triggered_by: str | None = None,
+    *,
+    initiator: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """Extra bus payload fields for canonical v1.1."""
+    init = initiator or (
+        get_thread_initiator(thread_id)
+        if thread_id
+        else None
+    )
+    if init is None and triggered_by:
+        init = build_initiator(triggered_by)
+    if init is None:
+        init = default_initiator()
+    out: dict[str, Any] = {"initiator": init}
+    if triggered_by:
+        out["triggered_by"] = triggered_by
+    return out

agentmetry/core/audit/sinks.py

@@ -0,0 +1,235 @@
+"""Agentmetry forward sinks — file, webhook, Elastic ECS, Splunk HEC."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+from threading import Lock
+from typing import Any
+
+import httpx
+
+from agentmetry.core.audit.adapters.ecs import canonical_to_ecs
+from agentmetry.core.audit.adapters.splunk import canonical_to_hec_event
+
+logger = logging.getLogger(__name__)
+
+_file_lock = Lock()
+
+
+class AuditSink(ABC):
+    @abstractmethod
+    async def emit(self, canonical: dict[str, Any]) -> None:
+        ...
+
+
+class FileAuditSink(AuditSink):
+    def __init__(self, path: Path) -> None:
+        self._path = path
+
+    async def emit(self, canonical: dict[str, Any]) -> None:
+        from agentmetry.core.audit.trail_chain import append_chained_line
+
+        with _file_lock:
+            append_chained_line(self._path, canonical)
+
+
+class WebhookAuditSink(AuditSink):
+    """POST each event to a URL, as the canonical record or a CloudEvent.
+
+    `format="cloudevents"` wraps the same record in a CloudEvents v1.0 structured
+    envelope, which is what brokers speak: Knative, EventBridge, Event Grid,
+    Dapr and the Kafka bindings all consume it. The canonical event still travels
+    whole inside `data`, so nothing is lost by choosing it.
+
+    Default stays `canonical`. Changing the shape of what an existing webhook
+    receives because a new option appeared would break every consumer already
+    wired up, and silently.
+    """
+
+    def __init__(
+        self, url: str, *, timeout_seconds: float = 5.0, format: str = "canonical"
+    ) -> None:
+        self._url = url
+        self._timeout = timeout_seconds
+        self._cloudevents = (format or "").strip().lower() in ("cloudevents", "cloudevent", "ce")
+
+    async def emit(self, canonical: dict[str, Any]) -> None:
+        payload = canonical
+        # `application/cloudevents+json` is what marks structured mode; a
+        # consumer distinguishes it from a bare JSON body by content type alone.
+        content_type = "application/json"
+        if self._cloudevents:
+            from agentmetry.core.audit.adapters.cloudevents import canonical_to_cloudevent
+
+            payload = canonical_to_cloudevent(canonical)
+            content_type = "application/cloudevents+json; charset=utf-8"
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.post(
+                    self._url,
+                    json=payload,
+                    headers={"Content-Type": content_type, "User-Agent": "Agentmetry/1.0"},
+                )
+                response.raise_for_status()
+        except Exception:
+            logger.exception("Audit webhook POST failed → %s", self._url)
+
+
+class ElasticEcsSink(AuditSink):
+    """Index one ECS document per event (Elasticsearch _doc API)."""
+
+    def __init__(
+        self,
+        base_url: str,
+        index: str,
+        api_key: str,
+        *,
+        timeout_seconds: float = 5.0,
+        verify_tls: bool = True,
+    ) -> None:
+        self._url = base_url.rstrip("/") + f"/{index}/_doc"
+        self._api_key = api_key
+        self._timeout = timeout_seconds
+        self._verify = verify_tls
+
+    async def emit(self, canonical: dict[str, Any]) -> None:
+        doc = canonical_to_ecs(canonical)
+        headers = {
+            "Content-Type": "application/json",
+            "Authorization": f"ApiKey {self._api_key}",
+            "User-Agent": "Agentmetry/1.0",
+        }
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout, verify=self._verify) as client:
+                response = await client.post(self._url, json=doc, headers=headers)
+                response.raise_for_status()
+        except Exception:
+            logger.exception("Elastic ECS index failed → %s", self._url)
+
+
+class SplunkHecSink(AuditSink):
+    """POST one event to Splunk HTTP Event Collector."""
+
+    def __init__(
+        self,
+        hec_url: str,
+        token: str,
+        *,
+        index: str = "main",
+        sourcetype: str = "agentmetry:json",
+        timeout_seconds: float = 5.0,
+        verify_tls: bool = True,
+    ) -> None:
+        base = hec_url.rstrip("/")
+        if base.endswith("/services/collector"):
+            self._url = base
+        elif base.endswith("/services/collector/event"):
+            self._url = base
+        else:
+            self._url = base + "/services/collector/event"
+        self._token = token
+        self._index = index
+        self._sourcetype = sourcetype
+        self._timeout = timeout_seconds
+        self._verify = verify_tls
+
+    async def emit(self, canonical: dict[str, Any]) -> None:
+        payload = canonical_to_hec_event(
+            canonical,
+            index=self._index,
+            sourcetype=self._sourcetype,
+        )
+        headers = {
+            "Authorization": f"Splunk {self._token}",
+            "Content-Type": "application/json",
+            "User-Agent": "Agentmetry/1.0",
+        }
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout, verify=self._verify) as client:
+                response = await client.post(self._url, json=payload, headers=headers)
+                response.raise_for_status()
+        except Exception:
+            logger.exception("Splunk HEC POST failed → %s", self._url)
+
+
+class MultiAuditSink(AuditSink):
+    def __init__(self, sinks: list[AuditSink]) -> None:
+        self._sinks = sinks
+
+    async def emit(self, canonical: dict[str, Any]) -> None:
+        for sink in self._sinks:
+            await sink.emit(canonical)
+
+
+def parse_sink_modes(raw: str) -> set[str]:
+    text = raw.strip().lower()
+    if not text or text == "file":
+        return {"file"}
+    if text == "both":
+        return {"file", "webhook"}
+    if text == "all":
+        return {"file", "webhook", "elastic", "splunk"}
+    return {part.strip() for part in text.split(",") if part.strip()}
+
+
+def build_audit_sinks(
+    *,
+    modes: set[str],
+    file_path: Path,
+    webhook_url: str,
+    webhook_timeout_seconds: float,
+    webhook_format: str = "canonical",
+    elastic_url: str,
+    elastic_index: str,
+    elastic_api_key: str,
+    elastic_verify_tls: bool,
+    splunk_hec_url: str,
+    splunk_hec_token: str,
+    splunk_index: str,
+    splunk_sourcetype: str,
+    splunk_verify_tls: bool,
+) -> AuditSink | None:
+    sinks: list[AuditSink] = []
+
+    if "file" in modes:
+        sinks.append(FileAuditSink(file_path))
+
+    if "webhook" in modes and webhook_url.strip():
+        sinks.append(
+            WebhookAuditSink(
+                webhook_url.strip(),
+                timeout_seconds=webhook_timeout_seconds,
+                format=webhook_format,
+            )
+        )
+
+    if "elastic" in modes and elastic_url.strip() and elastic_api_key.strip():
+        sinks.append(
+            ElasticEcsSink(
+                elastic_url.strip(),
+                elastic_index,
+                elastic_api_key.strip(),
+                timeout_seconds=webhook_timeout_seconds,
+                verify_tls=elastic_verify_tls,
+            )
+        )
+
+    if "splunk" in modes and splunk_hec_url.strip() and splunk_hec_token.strip():
+        sinks.append(
+            SplunkHecSink(
+                splunk_hec_url.strip(),
+                splunk_hec_token.strip(),
+                index=splunk_index,
+                sourcetype=splunk_sourcetype,
+                timeout_seconds=webhook_timeout_seconds,
+                verify_tls=splunk_verify_tls,
+            )
+        )
+
+    if not sinks:
+        return None
+    if len(sinks) == 1:
+        return sinks[0]
+    return MultiAuditSink(sinks)