panoptis 0.3.1__py3-none-any.whl

panopti/__init__.py

@@ -0,0 +1,166 @@
+"""Panopti: The All-Seeing Pre-Execution Guardrail & Forensic Engine for Autonomous AI.
+
+Panopti is the successor to AgentWatch, providing pre-execution contract verification,
+causal confidence decay tracking, cryptographic witness proofs, and deterministic forensic
+shadow replay for agent swarms.
+"""
+
+from __future__ import annotations
+
+try:
+    from panoptis._version import __version__
+except (ImportError, ModuleNotFoundError):
+    __version__ = "0.2.0"
+
+from panopti.attest import (
+    AttestationEngine,
+    PanoptiAttestationSeal,
+)
+from panopti.attest_keys import AttestationKeyError, Keyring, keyring_from_env
+from panopti.contracts import (
+    Contract,
+    ContractRegistry,
+    ContractViolationError,
+    Disallows,
+    MaxFrequency,
+    RequiresPrior,
+)
+from panopti.court import (
+    WitnessChain,
+    WitnessEntry,
+)
+from panopti.egress import (
+    EgressGuard,
+    SSRFBlockedError,
+)
+from panopti.killswitch import (
+    EmergencyKillSwitch,
+    EmergencyStopTriggered,
+)
+from panopti.mesh import (
+    SwarmAgentNode,
+    SwarmMesh,
+)
+from panopti.replay import (
+    DropStepPerturbation,
+    MutateResultPerturbation,
+    Perturbation,
+    RecordedCall,
+    ReplayReport,
+    ReplayTape,
+    ShadowReplayer,
+)
+from panopti.shield import (
+    AntiTamperShield,
+    TamperAttemptBlocked,
+)
+from panopti.synth import (
+    PolicySynthesizer,
+    SynthesizedInvariant,
+)
+
+try:
+    from panopti.doctor import run_diagnostics
+    from panopti.guard import (
+        GuardDecision,
+        PanoptiGuard,
+        guard,
+    )
+    from panoptis.causality import (
+        CUMULATIVE_CONFIDENCE_COLLAPSE,
+        ConfidenceCollapseWarning,
+        ConfidenceDecayTracker,
+    )
+    from panoptis.circuit_breaker import (
+        AgentLoopError,
+        AgentLoopException,
+        CircuitBreaker,
+        CircuitState,
+        CircuitThresholds,
+        LoopDetector,
+        TripReason,
+    )
+    from panoptis.core.watcher import (
+        AgentWatchBlockedError,
+        GenericAdapter,
+        detect_framework,
+        detect_framework_label,
+        watch,
+    )
+
+    PanoptiBlockedError = AgentWatchBlockedError
+except ImportError:  # pragma: no cover
+    watch = None  # type: ignore[assignment]
+    guard = None  # type: ignore[assignment]
+    detect_framework = None  # type: ignore[assignment]
+    detect_framework_label = None  # type: ignore[assignment]
+    GenericAdapter = None  # type: ignore[assignment]
+    AgentWatchBlockedError = Exception  # type: ignore[assignment,misc]
+    PanoptiBlockedError = AgentWatchBlockedError
+    CircuitBreaker = None  # type: ignore[assignment]
+    CircuitState = None  # type: ignore[assignment]
+    CircuitThresholds = None  # type: ignore[assignment]
+    TripReason = None  # type: ignore[assignment]
+    LoopDetector = None  # type: ignore[assignment]
+    AgentLoopError = Exception  # type: ignore[assignment,misc]
+    AgentLoopException = AgentLoopError
+    PanoptiGuard = None  # type: ignore[assignment]
+    GuardDecision = None  # type: ignore[assignment]
+    ConfidenceDecayTracker = None  # type: ignore[assignment]
+    CUMULATIVE_CONFIDENCE_COLLAPSE = "CUMULATIVE_CONFIDENCE_COLLAPSE"
+    ConfidenceCollapseWarning = None  # type: ignore[assignment]
+    run_diagnostics = None  # type: ignore[assignment]
+
+__all__ = [
+    "__version__",
+    "guard",
+    "watch",
+    "detect_framework",
+    "detect_framework_label",
+    "GenericAdapter",
+    "PanoptiBlockedError",
+    "AgentWatchBlockedError",
+    "CircuitBreaker",
+    "CircuitState",
+    "CircuitThresholds",
+    "TripReason",
+    "LoopDetector",
+    "AgentLoopError",
+    "AgentLoopException",
+    "ConfidenceDecayTracker",
+    "CUMULATIVE_CONFIDENCE_COLLAPSE",
+    "ConfidenceCollapseWarning",
+    "PanoptiGuard",
+    "GuardDecision",
+    "Contract",
+    "ContractRegistry",
+    "RequiresPrior",
+    "Disallows",
+    "MaxFrequency",
+    "ContractViolationError",
+    "WitnessEntry",
+    "WitnessChain",
+    "SwarmAgentNode",
+    "SwarmMesh",
+    "run_diagnostics",
+    "RecordedCall",
+    "ReplayTape",
+    "ShadowReplayer",
+    "ReplayReport",
+    "Perturbation",
+    "DropStepPerturbation",
+    "MutateResultPerturbation",
+    "PanoptiAttestationSeal",
+    "AttestationKeyError",
+    "Keyring",
+    "keyring_from_env",
+    "AttestationEngine",
+    "PolicySynthesizer",
+    "SynthesizedInvariant",
+    "EmergencyKillSwitch",
+    "EmergencyStopTriggered",
+    "AntiTamperShield",
+    "TamperAttemptBlocked",
+    "EgressGuard",
+    "SSRFBlockedError",
+]

panopti/__main__.py

@@ -0,0 +1,8 @@
+"""Panopti CLI entry point."""
+
+from __future__ import annotations
+
+from panoptis.cli.main import main
+
+if __name__ == "__main__":
+    main()

panopti/_banner.py

@@ -0,0 +1,37 @@
+"""Panopti ASCII Banner."""
+
+from __future__ import annotations
+
+import sys
+
+PANOPTI_ASCII_BANNER = r"""
+  ██████╗  █████╗ ███╗   ██╗ ██████╗ ██████╗ ████████╗██╗
+  ██╔══██╗██╔══██╗████╗  ██║██╔═══██╗██╔══██╗╚══██╔══╝██║
+  ██████╔╝███████║██╔██╗ ██║██║   ██║██████╔╝   ██║   ██║
+  ██╔═══╝ ██╔══██║██║╚██╗██║██║   ██║██╔═══╝    ██║   ██║
+  ██║     ██║  ██║██║ ╚████║╚██████╔╝██║        ██║   ██║
+  ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝        ╚═╝   ╚═╝
+     Argos Panoptes • All-Seeing Pre-Execution Guardrail
+"""
+
+PANOPTI_ASCII_BANNER_SAFE = r"""
+  ____                                _   _ 
+ |  _ \ __ _ _ __   ___  _ __  _   _ (_) | |
+ | |_) / _` | '_ \ / _ \| '_ \| |_| | | | |
+ |  __/ (_| | | | | (_) | |_) |  _  | | |_|
+ |_|   \__,_|_| |_|\___/| .__/|_| |_|_| (_)
+                        |_|                 
+     Argos Panoptes - All-Seeing Pre-Execution Guardrail
+"""
+
+
+def print_banner() -> None:
+    """Print banner safely across all terminal encodings (e.g. Windows cp1252/cp437)."""
+    encoding = getattr(sys.stdout, "encoding", None) or "utf-8"
+    try:
+        PANOPTI_ASCII_BANNER.encode(encoding)
+        sys.stdout.write(PANOPTI_ASCII_BANNER + "\n")
+        sys.stdout.flush()
+    except (UnicodeEncodeError, LookupError):
+        sys.stdout.write(PANOPTI_ASCII_BANNER_SAFE + "\n")
+        sys.stdout.flush()

panopti/attest.py

@@ -0,0 +1,175 @@
+"""Panopti Cryptographic Policy Attestation & Verifiable Audit Seals.
+
+Generates tamper-evident cryptographic seals for agent execution traces, proving
+formal invariant compliance and absence of runaway loops.
+Pure standard library (Ponytail: Ultra).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import uuid
+from dataclasses import asdict, dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from panopti.attest_keys import AttestationKeyError, Keyring, keyring_from_env
+
+
+def _canonical_json(data: Any) -> str:
+    """Serialize object to canonical, deterministic JSON."""
+    return json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=True)
+
+
+SEAL_VERSION = "2"
+
+
+@dataclass(slots=True)
+class PanoptiAttestationSeal:
+    """Cryptographic attestation certificate proving verified execution.
+
+    Version 2 seals name the key that signed them (``key_id``) and sign every field,
+    including the version and key id, as canonical JSON.
+    """
+
+    seal_id: str
+    merkle_root: str
+    policy_verdict: str
+    confidence_floor: float
+    loop_status: str
+    tool_count: int
+    timestamp_iso: str
+    signature: str
+    key_id: str | None = None
+    version: str = "1"
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2)
+
+    def signed_fields(self) -> dict[str, Any]:
+        d = self.to_dict()
+        d.pop("signature")
+        d["confidence_floor"] = f"{float(d['confidence_floor']):.4f}"
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PanoptiAttestationSeal:
+        return cls(
+            seal_id=data["seal_id"],
+            merkle_root=data["merkle_root"],
+            policy_verdict=data["policy_verdict"],
+            confidence_floor=float(data["confidence_floor"]),
+            loop_status=data["loop_status"],
+            tool_count=int(data["tool_count"]),
+            timestamp_iso=data["timestamp_iso"],
+            signature=data["signature"],
+            key_id=data.get("key_id"),
+            version=str(data.get("version", "1")),
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> PanoptiAttestationSeal:
+        return cls.from_dict(json.loads(json_str))
+
+
+def _keyring_for(keyring: Keyring | None, secret_key: str | bytes | None) -> Keyring:
+    """The keyring to use: explicit, else a one-key ring from ``secret_key``, else the env."""
+    if keyring is not None:
+        return keyring
+    if secret_key is not None:
+        ring = Keyring()
+        key = secret_key.encode() if isinstance(secret_key, str) else secret_key
+        ring.add("explicit", key)  # validated: strength, not a known public default
+        return ring
+    return keyring_from_env()
+
+
+class AttestationEngine:
+    """Issues and cryptographically validates Panopti attestation seals."""
+
+    @staticmethod
+    def _v1_payload(seal: PanoptiAttestationSeal) -> str:
+        return (
+            f"{seal.seal_id}|{seal.merkle_root}|{seal.policy_verdict}|"
+            f"{seal.confidence_floor:.4f}|{seal.loop_status}|{seal.tool_count}|{seal.timestamp_iso}"
+        )
+
+    @staticmethod
+    def _sign(key: bytes, seal: PanoptiAttestationSeal) -> str:
+        return hmac.new(
+            key, _canonical_json(seal.signed_fields()).encode(), hashlib.sha256
+        ).hexdigest()
+
+    @classmethod
+    def create_seal(
+        cls,
+        merkle_root: str,
+        tool_count: int,
+        confidence_floor: float = 1.0,
+        is_compliant: bool = True,
+        loop_detected: bool = False,
+        secret_key: str | bytes | None = None,
+        *,
+        keyring: Keyring | None = None,
+    ) -> PanoptiAttestationSeal:
+        """Issue a signed (version 2) attestation seal.
+
+        The key comes from ``keyring``, else ``secret_key`` (checked: at least 32 bytes,
+        not a known public key), else ``AGENTWATCH_ATTEST_KEYS``. There is no default key:
+        with none configured this raises :class:`AttestationKeyError`.
+        """
+        kid, key = _keyring_for(keyring, secret_key).signing_key()
+        seal = PanoptiAttestationSeal(
+            seal_id=f"seal_{uuid.uuid4().hex[:16]}",
+            merkle_root=merkle_root,
+            policy_verdict="COMPLIANT" if is_compliant else "VIOLATION",
+            confidence_floor=confidence_floor,
+            loop_status="LOOP_DETECTED" if loop_detected else "CLEAN",
+            tool_count=tool_count,
+            timestamp_iso=datetime.now(UTC).isoformat(),
+            signature="",
+            key_id=kid,
+            version=SEAL_VERSION,
+        )
+        seal.signature = cls._sign(key, seal)
+        return seal
+
+    @classmethod
+    def verify_seal(
+        cls,
+        seal: PanoptiAttestationSeal,
+        secret_key: str | bytes | None = None,
+        *,
+        keyring: Keyring | None = None,
+        allow_legacy: bool = False,
+    ) -> bool:
+        """True only if the seal was signed by a known, unrevoked key and is unmodified.
+
+        Fails closed: an unknown or revoked key id, a missing key or any modified field
+        returns False. Version 1 seals (no key id) verify only with ``allow_legacy=True``
+        and an explicit, non-public ``secret_key``.
+        """
+        try:
+            ring = _keyring_for(keyring, secret_key)
+        except AttestationKeyError:
+            return False
+        if seal.version == "1" or seal.key_id is None:
+            if not allow_legacy or secret_key is None:
+                return False
+            key = ring.verification_key("explicit")
+            if key is None:
+                return False
+            expected = hmac.new(key, cls._v1_payload(seal).encode(), hashlib.sha256).hexdigest()
+            return hmac.compare_digest(seal.signature, expected)
+        if seal.version != SEAL_VERSION:
+            return False
+        kid = seal.key_id if keyring is not None or secret_key is None else "explicit"
+        key = ring.verification_key(kid)
+        if key is None:
+            return False
+        return hmac.compare_digest(seal.signature, cls._sign(key, seal))

panopti/attest_keys.py

@@ -0,0 +1,202 @@
+"""Signing keys for attestation seals: a keyring with ids, rotation and revocation.
+
+Configuration (environment)::
+
+    AGENTWATCH_ATTEST_KEYS        kid=<base64 or hex key>,kid2=...   (one per line also works)
+    AGENTWATCH_ATTEST_ACTIVE_KID  the kid new seals are signed with (default: the last listed)
+    AGENTWATCH_ATTEST_REVOKED     kids that must no longer verify (comma separated)
+    AGENTWATCH_ATTEST_DEV_KEY=1   development only: an ephemeral random key for this process
+
+There is no built-in key. A key must be at least 32 bytes and must not be a known public
+default; the dev key is refused in production and cloud mode. Key material is never
+logged or included in exceptions.
+
+Generate a key::
+
+    python -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hmac
+import logging
+import os
+import re
+import secrets
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+MIN_KEY_BYTES = 32
+# Keys that shipped in source code; anyone can forge seals with them.
+KNOWN_PUBLIC_KEYS = frozenset({b"panopti-seal-default-key", b"panopti-demo-hmac-key"})
+_KID = re.compile(r"^[A-Za-z0-9_.\-]{1,64}$")
+
+
+class AttestationKeyError(ValueError):
+    """The signing-key configuration is missing or unsafe. The message never contains key material."""
+
+
+def decode_key(text: str) -> bytes:
+    """A key given as base64 (preferred) or hex."""
+    t = text.strip()
+    if re.fullmatch(r"[0-9a-fA-F]+", t) and len(t) % 2 == 0 and len(t) >= 2 * MIN_KEY_BYTES:
+        return bytes.fromhex(t)
+    try:
+        return base64.b64decode(t, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise AttestationKeyError("attestation key is neither valid base64 nor hex") from exc
+
+
+def check_key(kid: str, key: bytes) -> None:
+    if not _KID.match(kid):
+        raise AttestationKeyError(f"invalid key id {kid!r}")
+    if any(hmac.compare_digest(key, k) for k in KNOWN_PUBLIC_KEYS):
+        raise AttestationKeyError(
+            f"key {kid!r} is a known public default key; anyone could forge seals with it"
+        )
+    if len(key) < MIN_KEY_BYTES:
+        raise AttestationKeyError(
+            f"key {kid!r} is {len(key)} bytes; at least {MIN_KEY_BYTES} are required"
+        )
+
+
+def is_production() -> bool:
+    env = (os.environ.get("AGENTWATCH_ENV") or "").strip().lower()
+    cloud = (os.environ.get("AGENTWATCH_CLOUD_MODE") or "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+    return env in ("production", "prod") or cloud
+
+
+@dataclass
+class Keyring:
+    keys: dict[str, bytes] = field(default_factory=dict)
+    active_kid: str | None = None
+    revoked: frozenset[str] = frozenset()
+    ephemeral: bool = False  # the development-only random key
+
+    def add(self, kid: str, key: bytes, *, activate: bool = True) -> None:
+        check_key(kid, key)
+        self.keys[kid] = key
+        if activate or self.active_kid is None:
+            self.active_kid = kid
+
+    def signing_key(self) -> tuple[str, bytes]:
+        if not self.active_kid or self.active_kid not in self.keys:
+            raise AttestationKeyError("no active attestation signing key is configured")
+        if self.active_kid in self.revoked:
+            raise AttestationKeyError(
+                f"the active key {self.active_kid!r} is revoked; activate another key"
+            )
+        return self.active_kid, self.keys[self.active_kid]
+
+    def verification_key(self, kid: str) -> bytes | None:
+        """The key for ``kid``, or None if it is unknown or revoked (verification then fails)."""
+        if kid in self.revoked:
+            return None
+        return self.keys.get(kid)
+
+    def describe(self) -> dict[str, object]:
+        """Safe summary for diagnostics (no key material)."""
+        return {
+            "kids": sorted(self.keys),
+            "active_kid": self.active_kid,
+            "revoked": sorted(self.revoked),
+            "ephemeral": self.ephemeral,
+        }
+
+
+def parse_keys(raw: str | None) -> dict[str, bytes]:
+    out: dict[str, bytes] = {}
+    if not raw:
+        return out
+    for part in re.split(r"[,\n]", raw):
+        part = part.strip()
+        if not part:
+            continue
+        kid, sep, value = part.partition("=")
+        kid = kid.strip()
+        if not sep or not value.strip():
+            raise AttestationKeyError(
+                f"AGENTWATCH_ATTEST_KEYS: entry for {kid!r} must be kid=<key>"
+            )
+        if kid in out:
+            raise AttestationKeyError(f"AGENTWATCH_ATTEST_KEYS: key id {kid!r} is listed twice")
+        key = decode_key(value)
+        check_key(kid, key)
+        out[kid] = key
+    return out
+
+
+def keyring_from_env(environ: dict[str, str] | None = None) -> Keyring:
+    """The configured keyring. Raises :class:`AttestationKeyError` if it is missing or unsafe."""
+    env = os.environ if environ is None else environ
+    keys = parse_keys(env.get("AGENTWATCH_ATTEST_KEYS"))
+    revoked = frozenset(
+        k.strip() for k in (env.get("AGENTWATCH_ATTEST_REVOKED") or "").split(",") if k.strip()
+    )
+    ring = Keyring(keys=keys, revoked=revoked)
+    if keys:
+        active = (env.get("AGENTWATCH_ATTEST_ACTIVE_KID") or "").strip() or list(keys)[-1]
+        if active not in keys:
+            raise AttestationKeyError(
+                f"AGENTWATCH_ATTEST_ACTIVE_KID {active!r} is not in AGENTWATCH_ATTEST_KEYS"
+            )
+        ring.active_kid = active
+        return ring
+    if (env.get("AGENTWATCH_ATTEST_DEV_KEY") or "").strip().lower() in ("1", "true", "yes", "on"):
+        prod = (env.get("AGENTWATCH_ENV") or "").strip().lower() in ("production", "prod") or (
+            env.get("AGENTWATCH_CLOUD_MODE") or ""
+        ).strip().lower() in ("1", "true", "yes", "on")
+        if prod:
+            raise AttestationKeyError(
+                "AGENTWATCH_ATTEST_DEV_KEY is development-only and is refused in production/cloud mode"
+            )
+        logger.warning(
+            "attestation: using an ephemeral development key; seals will not verify in another process"
+        )
+        ring.keys["dev-ephemeral"] = secrets.token_bytes(MIN_KEY_BYTES)
+        ring.active_kid = "dev-ephemeral"
+        ring.ephemeral = True
+        return ring
+    raise AttestationKeyError(
+        "no attestation signing key configured: set AGENTWATCH_ATTEST_KEYS (see docs/ATTESTATION_KEYS.md); "
+        "for local development only, AGENTWATCH_ATTEST_DEV_KEY=1"
+    )
+
+
+def check_startup(environ: dict[str, str] | None = None) -> dict[str, object] | None:
+    """Startup gate for servers: in production/cloud mode, refuse unsafe attestation config.
+
+    Returns a key-free summary of the keyring when one is configured, None when
+    attestation is neither configured nor required. Raises :class:`AttestationKeyError`
+    (the server must not start) when, in production/cloud mode, keys are configured but
+    weak/public/malformed, the development key is requested, or
+    AGENTWATCH_REQUIRE_ATTESTATION=1 and no key is configured. Outside production, a
+    broken configuration is still an error; an absent one is not.
+    """
+    env = os.environ if environ is None else environ
+    prod = (env.get("AGENTWATCH_ENV") or "").strip().lower() in ("production", "prod") or (
+        env.get("AGENTWATCH_CLOUD_MODE") or ""
+    ).strip().lower() in ("1", "true", "yes", "on")
+    configured = bool((env.get("AGENTWATCH_ATTEST_KEYS") or "").strip())
+    dev = (env.get("AGENTWATCH_ATTEST_DEV_KEY") or "").strip().lower() in ("1", "true", "yes", "on")
+    required = (env.get("AGENTWATCH_REQUIRE_ATTESTATION") or "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+        "on",
+    )
+    if not (configured or dev or required):
+        return None
+    if prod and required and not configured:
+        raise AttestationKeyError(
+            "AGENTWATCH_REQUIRE_ATTESTATION=1 but AGENTWATCH_ATTEST_KEYS is not set"
+        )
+    return keyring_from_env(env).describe()