agentcop 0.1.0__py3-none-any.whl

agentcop-0.1.0.dist-info/METADATA

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: agentcop
+Version: 0.1.0
+Summary: Universal forensic auditor for agent systems — OTel-aligned event schema, pluggable violation detectors
+Author: Shay Mizuno, Hind Tagmouti
+License: MIT
+Project-URL: Homepage, https://github.com/trusthandoff/agentcop
+Project-URL: Repository, https://github.com/trusthandoff/agentcop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# sentinel-core
+
+**The cop for agent fleets.**
+
+Every agent fleet needs a cop. Agents delegate, handoff, and execute — and without forensic oversight, violations are invisible until they're incidents. `sentinel-core` is a universal auditor: ingest events from any agent system, run violation detectors, get structured findings.
+
+OTel-aligned schema. Pluggable detectors. Adapter bridge to your stack. Zero required infrastructure.
+
+```
+pip install sentinel-core
+```
+
+---
+
+## How it works
+
+```
+your agent system
+      │
+      ▼
+ SentinelAdapter          ← translate domain events to universal schema
+      │
+      ▼
+  Sentinel.ingest()       ← load SentinelEvents into the auditor
+      │
+      ▼
+  detect_violations()     ← run detectors, get ViolationRecords
+      │
+      ▼
+  report() / your sink    ← stdout, OTel, alerting, whatever
+```
+
+---
+
+## Quickstart
+
+```python
+from sentinel_core import Sentinel, SentinelEvent
+
+sentinel = Sentinel()
+
+# Feed it events (any source, any schema — adapt first)
+sentinel.ingest([
+    SentinelEvent(
+        event_id="evt-001",
+        event_type="packet_rejected",
+        timestamp="2026-03-31T12:00:00Z",
+        severity="ERROR",
+        body="packet rejected — TTL expired",
+        source_system="my-agent",
+        attributes={"packet_id": "pkt-abc", "reason": "ttl_expired"},
+    )
+])
+
+violations = sentinel.detect_violations()
+# [ViolationRecord(violation_type='rejected_packet', severity='ERROR', ...)]
+
+sentinel.report()
+# [ERROR] rejected_packet — packet rejected — TTL expired
+#   packet_id: pkt-abc
+#   reason: ttl_expired
+```
+
+Built-in detectors fire on four event types out of the box:
+
+| `event_type`            | Detector                      | Severity |
+|-------------------------|-------------------------------|----------|
+| `packet_rejected`       | `detect_rejected_packet`      | ERROR    |
+| `capability_stale`      | `detect_stale_capability`     | ERROR    |
+| `token_overlap_used`    | `detect_overlap_window`       | WARN     |
+| `ai_generated_payload`  | `detect_ai_generated_payload` | WARN     |
+
+---
+
+## Custom detectors
+
+Detectors are plain functions. Register as many as you need.
+
+```python
+from sentinel_core import Sentinel, SentinelEvent, ViolationRecord
+from typing import Optional
+
+def detect_unauthorized_tool(event: SentinelEvent) -> Optional[ViolationRecord]:
+    if event.event_type != "tool_call":
+        return None
+    if event.attributes.get("tool") in {"shell", "fs_write"}:
+        return ViolationRecord(
+            violation_type="unauthorized_tool",
+            severity="CRITICAL",
+            source_event_id=event.event_id,
+            trace_id=event.trace_id,
+            detail={"tool": event.attributes["tool"]},
+        )
+
+sentinel = Sentinel()
+sentinel.register_detector(detect_unauthorized_tool)
+```
+
+---
+
+## TrustHandoff adapter
+
+[TrustHandoff](https://github.com/trusthandoff/trusthandoff) ships a first-class adapter. If you're using `trusthandoff` for cryptographic delegation, plug it in directly:
+
+```python
+from trusthandoff.sentinel_adapter import TrustHandoffSentinelAdapter
+from sentinel_core import Sentinel
+
+adapter = TrustHandoffSentinelAdapter()
+sentinel = Sentinel()
+
+# raw_events: list of dicts from trusthandoff's forensic log
+sentinel.ingest(adapter.to_sentinel_event(e) for e in raw_events)
+
+violations = sentinel.detect_violations()
+sentinel.report()
+```
+
+The adapter maps trusthandoff's event fields — `packet_id`, `correlation_id`, `reason`, `event_type` — to the universal `SentinelEvent` schema. Severity is inferred from event type. Everything else lands in `attributes`.
+
+---
+
+## Write your own adapter
+
+Implement the `SentinelAdapter` protocol to bridge any system:
+
+```python
+from sentinel_core import SentinelAdapter, SentinelEvent
+from typing import Dict, Any
+
+class MySystemAdapter:
+    source_system = "my-system"
+
+    def to_sentinel_event(self, raw: Dict[str, Any]) -> SentinelEvent:
+        return SentinelEvent(
+            event_id=raw["id"],
+            event_type=raw["type"],
+            timestamp=raw["ts"],
+            severity=raw.get("level", "INFO"),
+            body=raw.get("message", ""),
+            source_system=self.source_system,
+            trace_id=raw.get("trace_id"),
+            attributes=raw.get("metadata", {}),
+        )
+```
+
+---
+
+## LangGraph integration *(coming soon)*
+
+Native LangGraph adapter that hooks into graph execution events — node calls, edge transitions, tool invocations — and surfaces violations without any manual instrumentation.
+
+```python
+# coming soon
+from sentinel_core.adapters.langgraph import LangGraphSentinelAdapter
+```
+
+---
+
+## OpenTelemetry export *(optional)*
+
+`sentinel-core` events use an OTel-aligned schema out of the box (`trace_id`, `span_id`, severity levels). To export events as OTel log records:
+
+```
+pip install sentinel-core[otel]
+```
+
+```python
+from sentinel_core.otel import OtelSentinelExporter
+from opentelemetry.sdk._logs import LoggerProvider
+
+exporter = OtelSentinelExporter(logger_provider=LoggerProvider())
+exporter.export(events)
+```
+
+Attributes are emitted under the `sentinel.*` namespace. `trace_id` and `span_id` are mapped to OTel trace context.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- `pydantic>=2.7`
+
+---
+
+## License
+
+MIT

agentcop-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+sentinel_core/__init__.py,sha256=p2IbFHjCD3guHav_Mj0kzVxbFTXuMta0P6wBfMQlKw4,682
+sentinel_core/event.py,sha256=-spz7zu6ahs1c8n-cuI_L-bXW-ttogS0RTAQkPOIcsY,1874
+sentinel_core/otel.py,sha256=SfoWWa99CsgSqzAFFwObZgaabBZKk784rRo27sJoqcI,4740
+sentinel_core/sentinel.py,sha256=i1um_G7d33OIXhCRljbbO3et4ihN1_1c_Y2C9BrzQuE,2702
+sentinel_core/violations.py,sha256=L0H4A3-5kONZQ3zLXJ7Mw8rUaIslV_tinT09_AncOKg,2438
+sentinel_core/adapters/__init__.py,sha256=XQzd5D2Jvf0eL1sAtapFJfCR47-CA5rl8AEkGlmg_C8,65
+sentinel_core/adapters/base.py,sha256=sUbRid0p9sWb_au8UPYWM4WFk2vhtLVYBifOLfn0FT8,941
+agentcop-0.1.0.dist-info/METADATA,sha256=qm3Bnv7VSOcpMFr6sP0eGmN9S9EjJpw-J0Iiy4mGwQI,6115
+agentcop-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentcop-0.1.0.dist-info/top_level.txt,sha256=CgoprkX69GcboqQHPuoetUJznlJK47tJz7CaOsWdtzY,14
+agentcop-0.1.0.dist-info/RECORD,,

agentcop-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentcop-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sentinel_core

sentinel_core/__init__.py

@@ -0,0 +1,29 @@
+from .event import SentinelEvent, ViolationRecord
+from .sentinel import Sentinel, ViolationDetector
+from .violations import (
+    DEFAULT_DETECTORS,
+    detect_ai_generated_payload,
+    detect_overlap_window,
+    detect_rejected_packet,
+    detect_stale_capability,
+)
+from .adapters import SentinelAdapter
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core schema
+    "SentinelEvent",
+    "ViolationRecord",
+    # Auditor
+    "Sentinel",
+    "ViolationDetector",
+    # Built-in detectors
+    "DEFAULT_DETECTORS",
+    "detect_rejected_packet",
+    "detect_stale_capability",
+    "detect_overlap_window",
+    "detect_ai_generated_payload",
+    # Adapter protocol
+    "SentinelAdapter",
+]

sentinel_core/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .base import SentinelAdapter
+
+__all__ = ["SentinelAdapter"]

sentinel_core/adapters/base.py

@@ -0,0 +1,37 @@
+"""
+SentinelAdapter protocol.
+
+Implement this to bridge any system's raw event dicts into SentinelEvents.
+The TrustHandoff adapter lives in trusthandoff.sentinel_adapter.
+"""
+
+from typing import Any, Dict, Protocol, runtime_checkable
+
+from sentinel_core.event import SentinelEvent
+
+
+@runtime_checkable
+class SentinelAdapter(Protocol):
+    """
+    Protocol for system-specific event adapters.
+
+    Implementors translate raw event dicts (or any domain object) into
+    the universal SentinelEvent schema.
+
+    Example::
+
+        class MySystemAdapter:
+            source_system = "my-system"
+
+            def to_sentinel_event(self, raw: dict) -> SentinelEvent:
+                return SentinelEvent(
+                    event_id=raw["id"],
+                    event_type=raw["type"],
+                    ...
+                )
+    """
+
+    source_system: str
+
+    def to_sentinel_event(self, raw: Dict[str, Any]) -> SentinelEvent:
+        ...

sentinel_core/event.py

@@ -0,0 +1,57 @@
+from datetime import datetime, timezone
+from typing import Any, Dict, Literal, Optional
+import uuid
+
+from pydantic import BaseModel, Field
+
+
+class SentinelEvent(BaseModel):
+    """
+    Universal forensic event — OTel Log Data Model aligned.
+
+    OTel field mapping:
+      TraceId           → trace_id
+      SpanId            → span_id
+      Timestamp         → timestamp
+      ObservedTimestamp → observed_at
+      SeverityText      → severity
+      Body              → body
+      Attributes        → attributes
+
+    Domain-specific fields (packet_id, capability_id, etc.) live in
+    `attributes` — the same pattern OTel uses for instrumentation libraries.
+    `source_system` identifies the adapter that produced the event.
+    """
+
+    event_id: str
+    event_type: str
+    timestamp: datetime
+    observed_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+    severity: Literal["INFO", "WARN", "ERROR", "CRITICAL"]
+    producer_id: Optional[str] = None
+    trace_id: Optional[str] = None     # OTel TraceId / correlation_id
+    span_id: Optional[str] = None      # OTel SpanId, optional
+    body: str
+    attributes: Dict[str, Any] = Field(default_factory=dict)
+    source_system: str
+
+
+class ViolationRecord(BaseModel):
+    """
+    Structured output of a violation detector.
+
+    `source_event_id` links back to the SentinelEvent that triggered detection.
+    `detail` carries violation-specific fields (reason, capability_id, model, …).
+    """
+
+    violation_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    violation_type: str
+    severity: Literal["WARN", "ERROR", "CRITICAL"]
+    detected_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
+    source_event_id: str
+    trace_id: Optional[str] = None
+    detail: Dict[str, Any] = Field(default_factory=dict)

sentinel_core/otel.py

@@ -0,0 +1,143 @@
+"""
+OpenTelemetry integration for sentinel-core.
+
+Install the optional dependency to use this module:
+
+    pip install sentinel-core[otel]
+
+This module provides:
+  - to_otel_log_record()  — convert a SentinelEvent to an OTel LogRecord
+  - OtelSentinelExporter  — emit SentinelEvents through a LoggerProvider
+
+Example::
+
+    from opentelemetry.sdk._logs import LoggerProvider
+    from opentelemetry.sdk._logs.export import SimpleLogRecordProcessor
+    from opentelemetry.sdk._logs.export.in_memory_span_exporter import InMemoryLogExporter
+    from sentinel_core.otel import OtelSentinelExporter
+
+    provider = LoggerProvider()
+    exporter = InMemoryLogExporter()
+    provider.add_log_record_processor(SimpleLogRecordProcessor(exporter))
+
+    sentinel_exporter = OtelSentinelExporter(logger_provider=provider)
+    sentinel_exporter.export(sentinel.detect_violations_as_events())
+"""
+
+from __future__ import annotations
+
+from datetime import timezone
+from typing import TYPE_CHECKING, List, Sequence
+
+from .event import SentinelEvent
+
+if TYPE_CHECKING:
+    pass
+
+_SEVERITY_NUMBER_MAP = {
+    "INFO": 9,       # OTel SeverityNumber.INFO
+    "WARN": 13,      # OTel SeverityNumber.WARN
+    "ERROR": 17,     # OTel SeverityNumber.ERROR
+    "CRITICAL": 21,  # OTel SeverityNumber.FATAL
+}
+
+
+def _require_otel() -> None:
+    try:
+        import opentelemetry  # noqa: F401
+    except ImportError as exc:
+        raise ImportError(
+            "OpenTelemetry integration requires 'opentelemetry-sdk'. "
+            "Install it with: pip install sentinel-core[otel]"
+        ) from exc
+
+
+def to_otel_attributes(event: SentinelEvent) -> dict:
+    """
+    Flatten a SentinelEvent into a flat OTel-compatible attribute dict.
+
+    All `attributes` keys are namespaced under `sentinel.*` to avoid
+    collisions with standard OTel resource/span attributes.
+    """
+    attrs: dict = {
+        "sentinel.event_id": event.event_id,
+        "sentinel.event_type": event.event_type,
+        "sentinel.source_system": event.source_system,
+    }
+    if event.producer_id is not None:
+        attrs["sentinel.producer_id"] = event.producer_id
+    if event.trace_id is not None:
+        attrs["sentinel.trace_id"] = event.trace_id
+    if event.span_id is not None:
+        attrs["sentinel.span_id"] = event.span_id
+    for k, v in event.attributes.items():
+        if v is not None:
+            attrs[f"sentinel.{k}"] = str(v)
+    return attrs
+
+
+def to_otel_log_record(event: SentinelEvent):
+    """
+    Convert a SentinelEvent to an opentelemetry.sdk._logs.LogRecord.
+
+    Requires ``opentelemetry-sdk`` to be installed.
+    """
+    _require_otel()
+    from opentelemetry.sdk._logs import LogRecord  # type: ignore[import]
+    from opentelemetry._logs.severity import SeverityNumber  # type: ignore[import]
+
+    severity_number_value = _SEVERITY_NUMBER_MAP.get(event.severity, 9)
+    severity_number = SeverityNumber(severity_number_value)
+
+    timestamp_ns = int(
+        event.timestamp.astimezone(timezone.utc).timestamp() * 1_000_000_000
+    )
+    observed_ns = int(
+        event.observed_at.astimezone(timezone.utc).timestamp() * 1_000_000_000
+    )
+
+    return LogRecord(
+        timestamp=timestamp_ns,
+        observed_timestamp=observed_ns,
+        severity_text=event.severity,
+        severity_number=severity_number,
+        body=event.body,
+        attributes=to_otel_attributes(event),
+        trace_id=int(event.trace_id, 16) if event.trace_id and len(event.trace_id) == 32 else 0,
+        span_id=int(event.span_id, 16) if event.span_id and len(event.span_id) == 16 else 0,
+    )
+
+
+class OtelSentinelExporter:
+    """
+    Emit SentinelEvents as OTel log records through a LoggerProvider.
+
+    Requires ``opentelemetry-sdk`` to be installed.
+
+    Parameters
+    ----------
+    logger_provider:
+        An ``opentelemetry.sdk._logs.LoggerProvider`` instance.
+        If None, uses the global provider.
+    instrumentation_name:
+        Logger name used when acquiring the OTel logger (appears as
+        ``otel.scope.name`` in most exporters).
+    """
+
+    def __init__(
+        self,
+        logger_provider=None,
+        instrumentation_name: str = "sentinel-core",
+    ):
+        _require_otel()
+        from opentelemetry.sdk._logs import LoggerProvider as _LP  # type: ignore[import]
+        from opentelemetry._logs import get_logger_provider  # type: ignore[import]
+
+        self._provider = logger_provider or get_logger_provider()
+        self._logger = self._provider.get_logger(instrumentation_name)
+
+    def export(self, events: Sequence[SentinelEvent]) -> None:
+        """Emit each event as an OTel log record."""
+        for event in events:
+            record = to_otel_log_record(event)
+            self._logger.emit(record)

sentinel_core/sentinel.py

@@ -0,0 +1,80 @@
+import threading
+from typing import Callable, Iterable, List, Optional
+
+from .event import SentinelEvent, ViolationRecord
+from .violations import DEFAULT_DETECTORS
+
+ViolationDetector = Callable[[SentinelEvent], Optional[ViolationRecord]]
+
+
+class Sentinel:
+    """
+    Universal forensic auditor.
+
+    Ingests SentinelEvents, runs violation detectors, returns typed ViolationRecords.
+
+    Usage::
+
+        sentinel = Sentinel()
+        sentinel.ingest(adapter.to_sentinel_event(e) for e in raw_events)
+        violations = sentinel.detect_violations()
+
+    Custom detectors::
+
+        def my_detector(event: SentinelEvent) -> ViolationRecord | None:
+            if event.event_type == "custom_alert":
+                return ViolationRecord(
+                    violation_type="custom_alert",
+                    severity="WARN",
+                    source_event_id=event.event_id,
+                    trace_id=event.trace_id,
+                    detail={"msg": event.body},
+                )
+
+        sentinel = Sentinel()
+        sentinel.register_detector(my_detector)
+    """
+
+    def __init__(self, detectors: Optional[List[ViolationDetector]] = None):
+        self._lock = threading.Lock()
+        self._events: List[SentinelEvent] = []
+        self._detectors: List[ViolationDetector] = (
+            list(detectors) if detectors is not None else list(DEFAULT_DETECTORS)
+        )
+
+    def register_detector(self, fn: ViolationDetector) -> None:
+        """Append a custom detector. Runs after all built-in detectors."""
+        with self._lock:
+            self._detectors.append(fn)
+
+    def ingest(self, events: Iterable[SentinelEvent]) -> None:
+        """Replace the internal event buffer with the provided events."""
+        ingested = list(events)
+        with self._lock:
+            self._events = ingested
+
+    def detect_violations(self) -> List[ViolationRecord]:
+        with self._lock:
+            events = list(self._events)
+            detectors = list(self._detectors)
+
+        violations: List[ViolationRecord] = []
+        for event in events:
+            for detector in detectors:
+                result = detector(event)
+                if result is not None:
+                    violations.append(result)
+        return violations
+
+    def report(self) -> None:
+        violations = self.detect_violations()
+        if not violations:
+            print("No violations detected")
+            return
+        print("=== SENTINEL REPORT ===")
+        for v in violations:
+            print(
+                f"[{v.severity}] {v.violation_type}"
+                + (f" trace={v.trace_id}" if v.trace_id else "")
+                + (f" {v.detail}" if v.detail else "")
+            )

sentinel_core/violations.py

@@ -0,0 +1,82 @@
+"""
+Built-in violation detectors for sentinel-core.
+
+Each detector is a plain function:
+    (SentinelEvent) -> ViolationRecord | None
+
+Return a ViolationRecord if the event represents a violation, None otherwise.
+Register custom detectors via Sentinel.register_detector().
+"""
+
+from typing import Optional
+
+from .event import SentinelEvent, ViolationRecord
+
+
+def detect_rejected_packet(event: SentinelEvent) -> Optional[ViolationRecord]:
+    if event.event_type != "packet_rejected":
+        return None
+    return ViolationRecord(
+        violation_type="rejected_packet",
+        severity="ERROR",
+        source_event_id=event.event_id,
+        trace_id=event.trace_id,
+        detail={
+            "packet_id": event.attributes.get("packet_id"),
+            "reason": event.attributes.get("reason"),
+        },
+    )
+
+
+def detect_stale_capability(event: SentinelEvent) -> Optional[ViolationRecord]:
+    if event.event_type != "capability_stale":
+        return None
+    return ViolationRecord(
+        violation_type="stale_capability",
+        severity="ERROR",
+        source_event_id=event.event_id,
+        trace_id=event.trace_id,
+        detail={
+            "capability_id": event.attributes.get("capability_id"),
+            "reason": event.attributes.get("reason"),
+        },
+    )
+
+
+def detect_overlap_window(event: SentinelEvent) -> Optional[ViolationRecord]:
+    if event.event_type != "token_overlap_used":
+        return None
+    return ViolationRecord(
+        violation_type="overlap_window_used",
+        severity="WARN",
+        source_event_id=event.event_id,
+        trace_id=event.trace_id,
+        detail={
+            "packet_id": event.attributes.get("packet_id"),
+            "reason": event.attributes.get("reason"),
+        },
+    )
+
+
+def detect_ai_generated_payload(event: SentinelEvent) -> Optional[ViolationRecord]:
+    if event.event_type != "ai_generated_payload":
+        return None
+    return ViolationRecord(
+        violation_type="ai_generated_payload",
+        severity="WARN",
+        source_event_id=event.event_id,
+        trace_id=event.trace_id,
+        detail={
+            "packet_id": event.attributes.get("packet_id"),
+            "source": event.attributes.get("source"),
+            "model": event.attributes.get("model"),
+        },
+    )
+
+
+DEFAULT_DETECTORS = [
+    detect_rejected_packet,
+    detect_stale_capability,
+    detect_overlap_window,
+    detect_ai_generated_payload,
+]