agentmetry 0.4.0__py3-none-any.whl

agentmetry/cli/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from agentmetry.cli import main
+
+sys.exit(main())

agentmetry/core/audit/__init__.py

@@ -0,0 +1 @@
+"""Audit artifacts — compliance evidence packs from the event outbox and run ledger."""

agentmetry/core/audit/adapters/agt.py

@@ -0,0 +1,304 @@
+"""Read Microsoft Agent Governance Toolkit audit files into the canonical trail.
+
+AGT governs agents you *build* -- Semantic Kernel, AutoGen, LangGraph, CrewAI --
+and its `FileAuditSink` writes hash-chained, HMAC-signed JSONL. Agentmetry hooks
+agents you *use*. Reading their file closes the gap between the two without
+either project writing a framework integration, and it gives AGT-governed
+activity the thing AGT does not do: sequence detection across a session, with
+MITRE tagging, so a credential read and a later egress become one finding.
+
+No dependency on their package. The integrity algorithm is reproduced here from
+their `SignedAuditEntry`, and a round-trip against a file produced by the real
+`FileAuditSink` 5.0.0 confirms it byte for byte. Depending on
+`agent-governance-toolkit-core` would pull 65 transitive requirements into a
+tool whose whole pitch is that it runs locally without them.
+
+## What their file actually looks like
+
+Their docs describe two different objects and it is easy to read one for the
+other. `AuditEntry` is the in-memory record and carries `entry_hash`;
+`SignedAuditEntry` is what `FileAuditSink` writes, and it carries
+`content_hash`, `previous_hash` and `signature` instead. There is no
+`entry_hash` on disk.
+
+What no document states, and what an external verifier actually needs, had to
+come from reading `SignedAuditEntry._canonical_payload`:
+
+- The content hash covers exactly fourteen fields, serialised with
+  `sort_keys=True` and `default=str`. `sandbox_id`, `environment` and
+  `compute_driver` are deliberately excluded so they can be added without
+  invalidating existing chains, and including them breaks every hash.
+- `previous_hash` links to the previous entry's **`content_hash`** -- not its
+  signature, which is the plausible wrong guess.
+- `signature` is HMAC-SHA256 over the **hex string** of the content hash, not
+  over its raw bytes.
+
+Also minor: `entry_id` is documented as a UUID and is in fact
+`audit_<first 16 hex of a uuid4>`, so it will not parse as one.
+
+All of this was established by generating a real file and reproducing its
+hashes, not by reading the reference.
+
+## Custody
+
+Ingested events are marked `source.tier = "external"` and `source.app = "agt"`,
+and they carry `provenance.captured_by = "agent-governance-toolkit"`. This is
+not decoration. Agentmetry did not observe these tool calls; it read someone
+else's record of them, and a trail that cannot tell the difference is making a
+claim it has no basis for. AGT's own maintainers concede the same gap in
+discussion #276: a sealed record does not prove faithful capture. Keeping the
+distinction visible is the least we can do about it here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+#: Fields covered by AGT's content hash, in their order-independent canonical
+#: payload. `sandbox_id`, `environment` and `compute_driver` are deliberately
+#: excluded by AGT so they can be added without invalidating existing chains;
+#: excluding them here too is what makes the hashes reproduce.
+_HASHED_FIELDS = (
+    "entry_id",
+    "timestamp",
+    "event_type",
+    "agent_did",
+    "action",
+    "resource",
+    "target_did",
+    "data",
+    "outcome",
+    "policy_decision",
+    "matched_rule",
+    "trace_id",
+    "session_id",
+    "previous_hash",
+)
+
+#: AGT event_type -> Agentmetry action.type.
+_ACTION_TYPE = {
+    "tool_invocation": "tool_called",
+    "tool_blocked": "tool_denied",
+    "policy_evaluation": "tool_called",
+    "policy_violation": "tool_denied",
+    "rogue_detection": "detection",
+    "agent_invocation": "session_start",
+}
+
+#: AGT policy verdict -> Agentmetry action.outcome, when AGT's own `outcome`
+#: is missing. AGT carries both a verdict (`action`) and a result (`outcome`);
+#: Agentmetry has one field, and the result is the more factual of the two.
+_OUTCOME = {
+    "allow": "success",
+    "deny": "denied",
+    "quarantine": "denied",
+    "warning": "success",
+    "audit": "success",
+}
+
+
+def content_hash(entry: dict[str, Any]) -> str:
+    """Recompute AGT's SHA-256 content hash for one entry."""
+    payload = {key: entry.get(key) for key in _HASHED_FIELDS}
+    return hashlib.sha256(
+        json.dumps(payload, sort_keys=True, default=str).encode()
+    ).hexdigest()
+
+
+def signature(content_hash_hex: str, secret_key: bytes) -> str:
+    """HMAC-SHA256 over the *hex string* of the content hash, as AGT does it."""
+    return hmac.new(secret_key, content_hash_hex.encode(), hashlib.sha256).hexdigest()
+
+
+@dataclass
+class AgtVerifyResult:
+    ok: bool
+    message: str
+    entries: int = 0
+    hash_failures: list[int] = field(default_factory=list)
+    chain_failures: list[int] = field(default_factory=list)
+    signature_failures: list[int] = field(default_factory=list)
+    signatures_checked: bool = False
+
+
+def read_agt_file(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    with Path(path).open("r", encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(record, dict) and "content_hash" in record:
+                rows.append(record)
+    return rows
+
+
+def verify_agt_chain(
+    rows: list[dict[str, Any]], secret_key: bytes | None = None
+) -> AgtVerifyResult:
+    """Check content hashes, chain linkage and (with a key) HMAC signatures.
+
+    Verified before ingest, never after. Importing someone else's audit record
+    into a hash-chained trail without checking it first would launder an
+    unverified claim into a chain that then vouches for it, and the chain would
+    be telling the truth about a lie.
+
+    The signature is optional because the key is optional. Without it the
+    content hashes and the linkage are still checkable, which catches editing
+    and reordering; only forgery by someone holding the key is out of reach,
+    and that is out of reach for AGT too.
+    """
+    if not rows:
+        return AgtVerifyResult(ok=True, message="no AGT entries found", entries=0)
+
+    hash_failures: list[int] = []
+    chain_failures: list[int] = []
+    signature_failures: list[int] = []
+    previous = ""
+
+    for index, row in enumerate(rows):
+        if content_hash(row) != str(row.get("content_hash") or ""):
+            hash_failures.append(index)
+        if str(row.get("previous_hash") or "") != previous:
+            chain_failures.append(index)
+        if secret_key is not None:
+            expected = signature(str(row.get("content_hash") or ""), secret_key)
+            if not hmac.compare_digest(expected, str(row.get("signature") or "")):
+                signature_failures.append(index)
+        previous = str(row.get("content_hash") or "")
+
+    problems = []
+    if hash_failures:
+        problems.append(f"{len(hash_failures)} content hash mismatch(es)")
+    if chain_failures:
+        problems.append(f"{len(chain_failures)} broken chain link(s)")
+    if signature_failures:
+        problems.append(f"{len(signature_failures)} bad signature(s)")
+
+    if problems:
+        first = min(
+            [i for group in (hash_failures, chain_failures, signature_failures) for i in group]
+        )
+        return AgtVerifyResult(
+            ok=False,
+            message=f"{', '.join(problems)}; first bad entry at index {first}",
+            entries=len(rows),
+            hash_failures=hash_failures,
+            chain_failures=chain_failures,
+            signature_failures=signature_failures,
+            signatures_checked=secret_key is not None,
+        )
+
+    checked = "hashes, chain and signatures" if secret_key is not None else "hashes and chain"
+    return AgtVerifyResult(
+        ok=True,
+        message=f"{len(rows)} AGT entries verified ({checked})",
+        entries=len(rows),
+        signatures_checked=secret_key is not None,
+    )
+
+
+def agt_to_canonical(
+    entry: dict[str, Any], *, host_id: str = "", fleet_id: str = ""
+) -> dict[str, Any]:
+    """Map one AGT entry onto an Agentmetry canonical event.
+
+    MITRE tagging and traits are computed here rather than carried across,
+    because AGT does not produce them and they are what lets the sequence rules
+    see this activity at all. That is the point of the adapter: AGT decides
+    allow or deny per call, and Agentmetry says what a session of those calls
+    adds up to.
+    """
+    from agentmetry.core.audit.detection.traits import classify_command
+    from agentmetry.core.audit.mitre import get_mitre_mapping
+
+    data = entry.get("data") if isinstance(entry.get("data"), dict) else {}
+    resource = str(entry.get("resource") or "")
+    command = str(data.get("command") or "")
+    event_type = str(entry.get("event_type") or "")
+    verdict = str(entry.get("action") or "")
+    outcome = str(entry.get("outcome") or "") or _OUTCOME.get(verdict, "success")
+
+    reason_parts = [p for p in (entry.get("policy_decision"), entry.get("matched_rule")) if p]
+
+    tool: dict[str, Any] = {
+        "name": resource.rsplit(".", 1)[-1] if resource else "",
+        "qualified": resource,
+        "server": resource.split(".", 1)[0] if "." in resource else "agt",
+        "arguments": data,
+        "parameters_redacted": False,
+    }
+    if command:
+        tool["command"] = command
+        tool["input_hash"] = hashlib.sha256(command.encode()).hexdigest()
+        tool["input_redaction"] = "hash+command"
+        traits = classify_command(command)
+        if traits:
+            tool["traits"] = traits
+    mapping = get_mitre_mapping(resource or "run", data or command)
+    if mapping:
+        tool["mitre"] = mapping
+
+    agent_did = str(entry.get("agent_did") or "")
+
+    return {
+        "schema_version": "1.1.0",
+        # AGT's entry_id is `audit_<16 hex>`, not a UUID, so it cannot be used
+        # as an event_id directly. Derived deterministically so re-importing the
+        # same file does not mint new identities for the same events.
+        "event_id": str(uuid.uuid5(uuid.NAMESPACE_URL, f"agt:{entry.get('entry_id')}")),
+        "correlation_id": str(entry.get("trace_id") or entry.get("session_id") or ""),
+        "session_id": str(entry.get("session_id") or ""),
+        "timestamp_utc": str(entry.get("timestamp") or ""),
+        "host_id": host_id,
+        "fleet_id": fleet_id,
+        "source_topic": f"external/agt/{_ACTION_TYPE.get(event_type, event_type or 'tool_called')}",
+        "source": {"tier": "external", "app": "agt", "adapter": "agt_file"},
+        "actor": {"type": "agent", "id": agent_did, "role": "agent"},
+        "initiator": {"actor_type": "agent", "trigger": "agt", "operator_id": agent_did},
+        "action": {
+            "type": _ACTION_TYPE.get(event_type, "tool_called"),
+            "outcome": outcome,
+            "reason": "; ".join(str(p) for p in reason_parts),
+        },
+        "agent": {"name": agent_did or "agt", "skill_id": ""},
+        "model": {"id": "", "provider": ""},
+        "tool": tool,
+        # Custody. Agentmetry did not observe this call; it read AGT's record of
+        # it. A trail that cannot say so is asserting more than it knows.
+        "provenance": {
+            "captured_by": "agent-governance-toolkit",
+            "agt_entry_id": entry.get("entry_id"),
+            "agt_content_hash": entry.get("content_hash"),
+            "agt_previous_hash": entry.get("previous_hash"),
+            "agt_event_type": event_type,
+            "agt_verdict": verdict,
+            "verified_on_import": True,
+        },
+    }
+
+
+def agt_file_to_canonical(
+    path: Path,
+    *,
+    secret_key: bytes | None = None,
+    host_id: str = "",
+    fleet_id: str = "",
+) -> tuple[AgtVerifyResult, list[dict[str, Any]]]:
+    """Verify an AGT file, then map it. Returns no events if verification fails."""
+    rows = read_agt_file(path)
+    result = verify_agt_chain(rows, secret_key)
+    if not result.ok:
+        return result, []
+    events = [agt_to_canonical(r, host_id=host_id, fleet_id=fleet_id) for r in rows]
+    return result, events

agentmetry/core/audit/adapters/cloudevents.py

@@ -0,0 +1,159 @@
+"""Map Agentmetry canonical events to CloudEvents v1.0 JSON envelopes.
+
+CloudEvents is a CNCF spec for describing an event's *envelope* -- who emitted
+it, what kind it is, when -- while leaving the payload alone. That is a good
+fit here: the canonical event is already the thing worth keeping, and this adds
+a routing header rather than a second schema to maintain.
+
+Why bother when ECS and HEC adapters already exist. Those two speak to one
+product each. CloudEvents is what a broker speaks: Knative, EventBridge, Azure
+Event Grid, Dapr, NATS and Kafka bindings all consume it, so one adapter
+reaches every consumer that is not a SIEM. It is also what Microsoft's Agent
+Governance Toolkit emits, which makes a shared bus between the two possible
+without either side writing a translator.
+
+Two decisions worth stating.
+
+**The canonical event travels whole, in `data`.** Flattening it into CloudEvents
+attributes would mean maintaining a second field list that drifts, and it would
+lose the parts that make the record worth having: the hash chain fields, the
+MITRE tagging, the traits. Extension attributes carry only what a *router*
+needs to make a decision without opening the payload.
+
+**Extension attribute names are lowercase alphanumeric.** CloudEvents 1.0 §3.1
+restricts them to `[a-z0-9]`, so no underscores and no dots. `agentmetryseq`
+looks wrong and is correct; a consumer that rejects `agentmetry_seq` is right
+to. This is the kind of rule that is easy to miss by copying an example, and
+the reference implementation this was cross-checked against gets it right too
+(`agentmeshentryhash`).
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+CE_SPECVERSION = "1.0"
+
+#: Reverse-DNS event types, per CloudEvents §3.1.1. Stable strings: a consumer
+#: filters on these, so renaming one is a breaking change for a subscriber the
+#: same way renaming a trait is for a stored event.
+_TYPE_PREFIX = "ai.agentmetry"
+
+_TYPE_MAP = {
+    "tool_called": f"{_TYPE_PREFIX}.tool.called",
+    "tool_denied": f"{_TYPE_PREFIX}.tool.denied",
+    "tool_failed": f"{_TYPE_PREFIX}.tool.failed",
+    "detection": f"{_TYPE_PREFIX}.detection.raised",
+    "detection_disposition": f"{_TYPE_PREFIX}.detection.dispositioned",
+    "approval_request": f"{_TYPE_PREFIX}.approval.requested",
+    "approval_response": f"{_TYPE_PREFIX}.approval.responded",
+    "session_start": f"{_TYPE_PREFIX}.session.started",
+    "session_end": f"{_TYPE_PREFIX}.session.ended",
+    "config_change": f"{_TYPE_PREFIX}.config.changed",
+}
+
+
+def cloudevent_type(action_type: str) -> str:
+    """Reverse-DNS type for an action, falling back rather than dropping.
+
+    An unmapped action still gets a well-formed type. Returning None or raising
+    would mean a new event type silently stops being forwarded, which is the
+    failure mode this project keeps finding in its own code.
+    """
+    action_type = (action_type or "unknown").strip() or "unknown"
+    return _TYPE_MAP.get(action_type, f"{_TYPE_PREFIX}.{action_type.replace('_', '.')}")
+
+
+def _rfc3339(ts: str) -> str:
+    """CloudEvents `time` must be RFC 3339. Canonical timestamps already are,
+    modulo the `+00:00` spelling of UTC, which is legal but reads oddly next to
+    every other CloudEvents producer."""
+    if not ts:
+        return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    return ts.replace("+00:00", "Z") if ts.endswith("+00:00") else ts
+
+
+def _source(canonical: dict[str, Any]) -> str:
+    """A URI-reference identifying the producer (CloudEvents §3.1.1).
+
+    Host plus the app being recorded, because "which machine and which agent"
+    is the question a subscriber routes on. Falls back to the bare scheme
+    rather than an empty string: `source` is REQUIRED and non-empty, and an
+    envelope that violates that gets rejected by a strict consumer.
+    """
+    host = str(canonical.get("host_id") or "").strip() or "unknown-host"
+    source = canonical.get("source") or {}
+    app = str(source.get("app") or "").strip()
+    return f"/agentmetry/{host}/{app}" if app else f"/agentmetry/{host}"
+
+
+def canonical_to_cloudevent(canonical: dict[str, Any]) -> dict[str, Any]:
+    """Wrap one canonical event in a CloudEvents v1.0 structured JSON envelope."""
+    action = canonical.get("action") or {}
+    tool = canonical.get("tool") or {}
+    detection = canonical.get("detection") or {}
+
+    action_type = str(action.get("type") or "")
+
+    envelope: dict[str, Any] = {
+        "specversion": CE_SPECVERSION,
+        "id": str(canonical.get("event_id") or ""),
+        "source": _source(canonical),
+        "type": cloudevent_type(action_type),
+        "time": _rfc3339(str(canonical.get("timestamp_utc") or "")),
+        "datacontenttype": "application/json",
+        "dataschema": f"https://agentmetry.ai/schemas/event/{canonical.get('schema_version') or '1.1.0'}",
+        # The canonical record, unflattened. It is the artifact worth keeping.
+        "data": canonical,
+    }
+
+    # `subject` is what the event is *about*, and it is what a human reads in a
+    # broker console. A detection is about its rule; a tool call is about its
+    # tool. Omitted rather than blank when neither applies: CloudEvents forbids
+    # empty-string attributes.
+    subject = str(detection.get("rule_id") or tool.get("qualified") or tool.get("name") or "")
+    if subject:
+        envelope["subject"] = subject
+
+    # Extension attributes: only what a router needs in order to filter without
+    # parsing `data`.
+    #
+    # Names are lowercase alphanumeric and at most 20 characters, both from the
+    # CloudEvents 1.0 attribute-naming rules. The length limit is a SHOULD and
+    # easy to miss, since it appears in the spec prose and in none of the
+    # examples: the obvious `agentmetrycorrelationid` is 23 and had to be cut to
+    # `agentmetrycorrid`. Some brokers enforce it, and a rejected envelope is a
+    # dropped event.
+    extensions = {
+        "agentmetrycorrid": canonical.get("correlation_id"),
+        "agentmetrysession": canonical.get("session_id"),
+        "agentmetryfleet": canonical.get("fleet_id"),
+        "agentmetryoutcome": action.get("outcome"),
+        "agentmetryseverity": detection.get("severity"),
+        "agentmetryrule": detection.get("rule_id"),
+    }
+    for key, value in extensions.items():
+        text = str(value or "").strip()
+        if text:
+            envelope[key] = text
+
+    return envelope
+
+
+def canonical_to_cloudevents(events: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [canonical_to_cloudevent(event) for event in events]
+
+
+#: CloudEvents §3.1: extension attribute names are lowercase alphanumeric.
+#: Exposed so a test can assert it over the envelopes rather than restating it.
+_RESERVED = frozenset(
+    {
+        "specversion", "id", "source", "type", "time",
+        "datacontenttype", "dataschema", "subject", "data",
+    }
+)
+
+
+def extension_attributes(envelope: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in envelope.items() if k not in _RESERVED}

agentmetry/core/audit/adapters/ecs.py

@@ -0,0 +1,103 @@
+"""Map Agentmetry canonical events to Elastic Common Schema (ECS) documents."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _parse_timestamp(ts: str) -> str:
+    if not ts:
+        return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    return ts.replace("+00:00", "Z") if ts.endswith("+00:00") else ts
+
+
+def _event_category(action_type: str) -> list[str]:
+    """Map a canonical action type onto ECS `event.category`.
+
+    ECS categories drive Elastic's prebuilt dashboards and detection rules, so a
+    correlated finding filed under `process` disappears among the tool calls it
+    was raised about. `intrusion_detection` is the category Elastic reserves for
+    exactly this: an alert produced by a rule rather than an observation.
+
+    A denied tool call is both a process event and the enforcement of a policy,
+    which is why it carries two categories. ECS is explicitly multi-valued here.
+    """
+    if action_type == "detection":
+        return ["intrusion_detection"]
+    if action_type in ("tool_denied", "tool_failed"):
+        return ["process", "intrusion_detection"]
+    if action_type in ("tool_called", "session_start", "session_end"):
+        return ["process"]
+    if action_type == "config_change":
+        return ["configuration"]
+    if action_type.startswith("approval") or action_type == "detection_disposition":
+        return ["iam"]
+    return ["process"]
+
+
+def canonical_to_ecs(canonical: dict[str, Any]) -> dict[str, Any]:
+    """Best-effort ECS 8.x field mapping; full canonical nested under agentmetry."""
+    action = canonical.get("action") or {}
+    actor = canonical.get("actor") or {}
+    tool = canonical.get("tool") or {}
+    model = canonical.get("model") or {}
+    agent = canonical.get("agent") or {}
+
+    action_type = str(action.get("type") or "")
+    outcome = str(action.get("outcome") or "")
+
+    doc: dict[str, Any] = {
+        "@timestamp": _parse_timestamp(str(canonical.get("timestamp_utc") or "")),
+        "event": {
+            "id": canonical.get("event_id"),
+            "kind": "event",
+            "category": _event_category(action_type),
+            "type": ["info"],
+            "action": action_type,
+            "outcome": outcome,
+            "reason": action.get("reason") or "",
+            "sequence": canonical.get("seq"),
+        },
+        "host": {"name": canonical.get("host_id")},
+        "user": {
+            "id": actor.get("id"),
+            "roles": [actor.get("role")] if actor.get("role") else [],
+        },
+        "trace": {"id": canonical.get("correlation_id")},
+        "session": {"id": canonical.get("session_id")},
+        "observer": {
+            "type": "agentmetry",
+            "vendor": "agentmetry",
+            "product": "Agentmetry",
+        },
+        "agent": {
+            "name": agent.get("name"),
+            "version": canonical.get("schema_version"),
+        },
+        "agentmetry": canonical,
+    }
+
+    if tool:
+        doc["tool"] = {
+            "name": tool.get("name"),
+            "type": tool.get("qualified"),
+        }
+        doc["service"] = {"name": tool.get("server")}
+
+    if model.get("id"):
+        doc["gen_ai"] = {
+            "request": {
+                "model": model.get("id"),
+            },
+            "system": model.get("provider"),
+        }
+
+    if outcome == "denied":
+        doc["event"]["type"] = ["denied"]
+
+    fleet_id = str(canonical.get("fleet_id") or "").strip()
+    if fleet_id:
+        doc["organization"] = {"id": fleet_id}
+
+    return doc

agentmetry/core/audit/adapters/splunk.py

@@ -0,0 +1,40 @@
+"""Splunk HEC envelope for Agentmetry canonical events."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def _epoch_seconds(ts: str) -> float:
+    if not ts:
+        return datetime.now(timezone.utc).timestamp()
+    normalized = ts.replace("Z", "+00:00")
+    try:
+        return datetime.fromisoformat(normalized).timestamp()
+    except ValueError:
+        return datetime.now(timezone.utc).timestamp()
+
+
+def canonical_to_hec_event(
+    canonical: dict[str, Any],
+    *,
+    index: str,
+    sourcetype: str,
+    source: str = "Agentmetry",
+) -> dict[str, Any]:
+    action = canonical.get("action") or {}
+    return {
+        "time": _epoch_seconds(str(canonical.get("timestamp_utc") or "")),
+        "host": canonical.get("host_id"),
+        "source": source,
+        "sourcetype": sourcetype,
+        "index": index,
+        "fields": {
+            "action_type": action.get("type"),
+            "action_outcome": action.get("outcome"),
+            "correlation_id": canonical.get("correlation_id"),
+            "actor_id": (canonical.get("actor") or {}).get("id"),
+        },
+        "event": canonical,
+    }

agentmetry/core/audit/alerts.py

@@ -0,0 +1,56 @@
+"""Alerting engine for high-severity audit events."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+
+class AlertWebhookSink:
+    """Fires webhooks (Slack/Discord) for high-severity events."""
+
+    def __init__(self, url: str, *, timeout_seconds: float = 5.0) -> None:
+        self._url = url
+        self._timeout = timeout_seconds
+
+    async def emit(self, canonical: dict[str, Any]) -> None:
+        action = canonical.get("action", {})
+        outcome = action.get("outcome")
+
+        # Only fire on denied or error
+        if outcome not in ("denied", "error"):
+            return
+
+        tool = canonical.get("tool", {})
+        tool_name = tool.get("qualified", "unknown_tool")
+        agent_name = canonical.get("agent", {}).get("skill_id") or canonical.get("source", {}).get("app", "unknown_agent")
+
+        text = f"🚨 *Agentmetry Alert*\nAgent `{agent_name}` attempted to run `{tool_name}` but the action resulted in `{outcome}`."
+
+        payload = {
+            "text": text,
+            "blocks": [
+                {
+                    "type": "section",
+                    "text": {
+                        "type": "mrkdwn",
+                        "text": text
+                    }
+                }
+            ]
+        }
+
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.post(
+                    self._url,
+                    json=payload,
+                    headers={"Content-Type": "application/json", "User-Agent": "Agentmetry-Alerts/1.0"},
+                )
+                response.raise_for_status()
+        except Exception:
+            logger.exception("Alert webhook POST failed → %s", self._url)