warrantkit 0.1.0__py3-none-any.whl

agentcontain/__init__.py

@@ -0,0 +1,90 @@
+"""WarrantKit platform primitives.
+
+The platform layer defines policy, execution identity, lifecycle state, structured
+events, and transport-neutral evidence around the AgentContainment engine.
+"""
+
+from .engine import (
+    Admission,
+    admit,
+    build_agentcontainment_engine,
+    containment_receipt,
+    detect,
+    evidence_envelope,
+    halt,
+    issue_recovery_authorization,
+    recover,
+    recontain,
+    verify,
+)
+from .events import Event, EventLog
+from .evidence import EvidenceEnvelope, canonical_json
+from .external_evidence import ExternalEvidenceReference
+from .fleet import Agent, FleetRegistry, FleetScope, Organization, Project, Runtime
+from .fleet_status import FleetPolicyStatus, fleet_policy_status
+from .fleet_status_history import FleetPolicyStatusHistory, FleetPolicyStatusSnapshot
+from .identity import ExecutionIdentity
+from .incident import IncidentStatus, IncidentSummary
+from .operator import EvidenceTimelineEvent, OperatorIncidentView
+from .policy import Policy
+from .policy_assignment import AssignmentState, PolicyAssignment, PolicyAssignmentRegistry
+from .policy_reconciliation import (
+    RolloutReconciliation,
+    TargetReconciliation,
+    TargetReconciliationState,
+    reconcile_rollout,
+)
+from .policy_rollout import Rollout, RolloutState
+from .policy_distribution import PolicyBundle, PolicyRegistry
+from .state import LifecycleState, PlatformStateMachine
+from .store import EvidenceStore, InMemoryEvidenceStore
+
+__all__ = [
+    "Admission",
+    "Event",
+    "EventLog",
+    "EvidenceStore",
+    "InMemoryEvidenceStore",
+    "EvidenceEnvelope",
+    "ExternalEvidenceReference",
+    "Agent",
+    "FleetRegistry",
+    "FleetScope",
+    "Organization",
+    "Project",
+    "Runtime",
+    "FleetPolicyStatus",
+    "fleet_policy_status",
+    "FleetPolicyStatusHistory",
+    "FleetPolicyStatusSnapshot",
+    "ExecutionIdentity",
+    "IncidentStatus",
+    "IncidentSummary",
+    "EvidenceTimelineEvent",
+    "OperatorIncidentView",
+    "LifecycleState",
+    "PlatformStateMachine",
+    "Policy",
+    "AssignmentState",
+    "PolicyAssignment",
+    "PolicyAssignmentRegistry",
+    "TargetReconciliationState",
+    "TargetReconciliation",
+    "RolloutReconciliation",
+    "reconcile_rollout",
+    "Rollout",
+    "RolloutState",
+    "PolicyBundle",
+    "PolicyRegistry",
+    "admit",
+    "build_agentcontainment_engine",
+    "canonical_json",
+    "containment_receipt",
+    "detect",
+    "evidence_envelope",
+    "halt",
+    "issue_recovery_authorization",
+    "recover",
+    "recontain",
+    "verify",
+]

agentcontain/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

agentcontain/cli.py

@@ -0,0 +1,154 @@
+"""Small operator-facing WarrantKit CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .engine import (
+    admit,
+    build_agentcontainment_engine,
+    containment_receipt,
+    contain,
+    evidence_envelope,
+)
+from .policy import Policy
+
+
+def _policy_from_args(args: argparse.Namespace) -> Policy:
+    return Policy(policy_id=args.policy, capabilities=tuple(args.capability), allowed_egress=tuple(args.egress))
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="warrantkit", description="WarrantKit runtime authorization, enforcement, and proof platform for autonomous AI agents.")
+    sub = parser.add_subparsers(dest="command", required=True)
+    inspect = sub.add_parser("inspect", help="inspect an evidence envelope as an operator incident")
+    inspect.add_argument("--evidence-file", required=True, help="JSON evidence envelope produced by WarrantKit")
+    inspect.add_argument("--json", action="store_true", help="emit the complete operator view as JSON")
+    demo = sub.add_parser("demo", help="run the no-root proof semantics demo")
+    run = sub.add_parser("run", help="admit an execution and optionally contain it")
+    run.add_argument("--policy", required=True, help="policy identifier")
+    run.add_argument("--agent-id", default="agent", help="agent identity")
+    run.add_argument("--capability", action="append", default=[], help="declared capability")
+    run.add_argument("--egress", action="append", default=[], help="allowed egress target")
+    run.add_argument("--cgroup-path", help="existing Linux cgroup-v2 path for this workload")
+    run.add_argument("--receipt-secret-file", help="read the HMAC receipt secret from a file instead of exposing it in argv")
+    run.add_argument("--receipt-secret-env", default="WARRANTKIT_RECEIPT_SECRET", help="environment variable containing the HMAC receipt secret")
+    run.add_argument("--evidence-output", help="write the complete evidence envelope to this JSON file")
+    run.add_argument("--contain", action="store_true", help="invoke external containment immediately after admission")
+    run.add_argument("--json", action="store_true", help="emit machine-readable execution state")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "inspect":
+        try:
+            from .evidence import EvidenceEnvelope
+            from .operator import OperatorIncidentView
+            envelope = EvidenceEnvelope.from_json(Path(args.evidence_file).read_text(encoding="utf-8"))
+            view = OperatorIncidentView.from_evidence(envelope)
+            if args.json:
+                print(json.dumps(view.to_dict(), sort_keys=True, indent=2))
+            else:
+                incident = view.incident
+                print(f"Incident {incident.incident_id}")
+                print(f"  Agent:        {view.agent.get('agent_id', 'unknown')}")
+                print(f"  Policy:       {view.policy.get('policy_id', 'unknown')}")
+                print(f"  Event:        {incident.trigger or 'none'}")
+                print(f"  Status:       {incident.status.value.upper()}")
+                print(f"  Proof:        {incident.proof_status}")
+                if view.receipt_id:
+                    print(f"  Receipt:      {view.receipt_id}")
+                print("  Timeline:")
+                for event in view.timeline:
+                    print(f"    {event.sequence}. {event.name}")
+            return 0
+        except Exception as exc:
+            print(f"warrantkit: {exc}", file=sys.stderr)
+            return 1
+    if args.command == "demo":
+        from .demo import run_demo
+        return run_demo()
+    if args.command == "run":
+        policy = _policy_from_args(args)
+        try:
+            engine = build_agentcontainment_engine(args.agent_id, cgroup_path=args.cgroup_path)
+            admission = admit(policy, agent_id=args.agent_id, engine=engine)
+            report = contain(admission) if args.contain else None
+
+            receipt_secret = None
+            if args.receipt_secret_file:
+                receipt_secret = Path(args.receipt_secret_file).read_text(encoding="utf-8").rstrip("\r\n").encode("utf-8")
+            elif args.receipt_secret_env:
+                configured_secret = os.environ.get(args.receipt_secret_env)
+                if configured_secret:
+                    receipt_secret = configured_secret.encode("utf-8")
+                elif args.receipt_secret_env == "WARRANTKIT_RECEIPT_SECRET":
+                    legacy_secret = os.environ.get("AGENTCONTAIN_RECEIPT_SECRET")
+                    if legacy_secret:
+                        receipt_secret = legacy_secret.encode("utf-8")
+
+            receipt = (
+                containment_receipt(admission, receipt_secret)
+                if receipt_secret is not None and report is not None
+                else None
+            )
+            envelope = evidence_envelope(admission)
+            if receipt is not None:
+                envelope = envelope.with_receipt(receipt.to_dict())
+
+            payload = {
+                "execution_id": admission.identity.execution_id,
+                "agent_id": admission.identity.agent_id,
+                "policy_id": admission.identity.policy_id,
+                "policy_digest": admission.identity.policy_digest,
+                "epoch": admission.identity.epoch,
+                "state": admission.machine.state.value,
+                "events": [event.to_dict() for event in admission.machine.events.events],
+            }
+            if report is not None:
+                payload["containment"] = {
+                    "complete": report.complete,
+                    "certified": getattr(report, "certified", False),
+                    "durable": getattr(report, "durable", False),
+                    "external_verified": getattr(report, "external_verified", False),
+                    "enforcement_latency_seconds": getattr(report, "enforcement_latency_seconds", None),
+                    "failures": list(getattr(report, "failures", ())),
+                }
+                if receipt is not None:
+                    payload["receipt"] = receipt.to_dict()
+
+            if args.evidence_output:
+                Path(args.evidence_output).write_text(
+                    envelope.to_json() + "\n",
+                    encoding="utf-8",
+                )
+
+            if args.json:
+                print(json.dumps(payload, sort_keys=True, indent=2))
+            else:
+                print(f"WarrantKit execution {payload['execution_id']}")
+                print(f"  Agent:  {payload['agent_id']}")
+                print(f"  Policy: {payload['policy_id']}")
+                print(f"  Epoch:  {payload['epoch']}")
+                print(f"  State:  {payload['state'].upper()}")
+                for event in admission.machine.events.events:
+                    print(f"  Event:  {event.name}")
+                if report is not None:
+                    status = "VERIFIED" if report.certified and report.durable else "DEGRADED"
+                    print(f"  Containment: {status}")
+                if args.evidence_output:
+                    print(f"  Evidence: {args.evidence_output}")
+            return 0
+        except Exception as exc:
+            print(f"warrantkit: {exc}", file=sys.stderr)
+            return 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentcontain/demo.py

@@ -0,0 +1,124 @@
+"""No-privilege demonstration of WarrantKit lifecycle and proof semantics."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from dataclasses import dataclass
+from typing import Any
+
+from .engine import admit, evidence_envelope
+from .evidence import EvidenceEnvelope, canonical_json
+from .operator import OperatorIncidentView
+from .policy import Policy
+
+_DEMO_KEY = b"warrantkit-demo-key-v1"
+
+
+@dataclass(frozen=True)
+class DemoReport:
+    complete: bool = True
+
+
+class SimulatedEngine:
+    """Demo-only engine. It does not enforce a kernel boundary."""
+
+    def contain(self) -> DemoReport:
+        return DemoReport()
+
+
+def _issue_receipt(evidence: EvidenceEnvelope) -> dict[str, Any]:
+    payload = {
+        "schema_version": 1,
+        "receipt_id": "demo-" + evidence.execution["execution_id"],
+        "execution_id": evidence.execution["execution_id"],
+        "agent_id": evidence.execution["agent_id"],
+        "epoch": evidence.execution["epoch"],
+        "containment": {
+            "requested": True,
+            "enforced": True,
+            "independently_verified": False,
+            "mode": "simulated",
+        },
+        "proof_status": "observed",
+    }
+    digest = hashlib.sha256(canonical_json(payload).encode("utf-8")).hexdigest()
+    signature = hmac.new(_DEMO_KEY, digest.encode("ascii"), hashlib.sha256).hexdigest()
+    return {"payload": payload, "digest": digest, "signature": signature}
+
+
+def _verify_receipt(receipt: dict[str, Any], evidence: EvidenceEnvelope) -> bool:
+    payload = receipt["payload"]
+    digest = hashlib.sha256(canonical_json(payload).encode("utf-8")).hexdigest()
+    signature = hmac.new(_DEMO_KEY, digest.encode("ascii"), hashlib.sha256).hexdigest()
+    return (
+        hmac.compare_digest(digest, receipt["digest"])
+        and hmac.compare_digest(signature, receipt["signature"])
+        and payload["execution_id"] == evidence.execution["execution_id"]
+        and payload["agent_id"] == evidence.execution["agent_id"]
+        and payload["epoch"] == evidence.execution["epoch"]
+    )
+
+
+def run_demo() -> int:
+    admission = admit(
+        Policy("demo", capabilities=("simulated-containment",)),
+        agent_id="demo-agent",
+        engine=SimulatedEngine(),
+    )
+    if not admission.engine.contain().complete:
+        raise RuntimeError("simulated containment failed")
+
+    admission.machine.contain()
+    admission.machine.detect({"reason": "demo_policy_violation"})
+    admission.machine.fence()
+    admission.machine.halt()
+    admission.machine.verify()
+
+    base = evidence_envelope(admission)
+    evidence = EvidenceEnvelope.from_execution(
+        execution=base.execution,
+        events=base.events,
+        enforcement={"complete": True, "mode": "simulated", "external_enforcement": False},
+        verification={"status": "observed", "method": "warrantkit-no-root-demo"},
+        proof={"simulated": True, "host_enforcement_verified": False},
+        provenance={"producer": "warrantkit-demo"},
+    )
+    receipt = _issue_receipt(evidence)
+    evidence = evidence.with_receipt(receipt)
+    evidence.validate()
+
+    if not _verify_receipt(receipt, evidence):
+        raise RuntimeError("demo receipt verification failed")
+
+    view = OperatorIncidentView.from_evidence(evidence)
+    incident = view.incident
+
+    print("WarrantKit — reference incident experience")
+    print("--------------------------------------------")
+    print(f"Execution:     {admission.identity.execution_id}")
+    print(f"Agent:         {view.agent['agent_id']}")
+    print(f"Policy:        {view.policy['policy_id']}")
+    print(f"Policy digest: {view.policy['policy_digest']}")
+    print("Mode:          SIMULATED (no kernel enforcement)")
+    print()
+    print("Incident")
+    print(f"  Trigger:     {incident.trigger or 'none'}")
+    print(f"  Status:      {incident.status.value.upper()}")
+    print(f"  Proof:       {incident.proof_status.upper()}")
+    print()
+    print("Lifecycle / evidence")
+    for event in view.timeline:
+        print(f"  {event.sequence}. {event.name}")
+    print()
+    print("Proof")
+    print("  Evidence:    OBSERVED")
+    print("  Verification: NOT CLAIMED (simulated)")
+    print("  Receipt:     AUTHENTICATED")
+    print(f"  Receipt ID:  {view.receipt_id}")
+    print()
+    print("Verified ≠ claim is true")
+    print("This reference experience demonstrates the platform procedure,")
+    print("operator projection, and receipt integrity.")
+    print("It does not prove real host or kernel containment.")
+    return 0