clawzero 0.1.0__py3-none-any.whl

clawzero/__init__.py

@@ -0,0 +1,69 @@
+"""
+ClawZero - Execution Firewall for AI Agents
+
+ClawZero wraps AI agent tools with MVAR runtime governance,
+blocking attacker-influenced executions at critical sinks.
+
+Example usage:
+    from clawzero import protect
+
+    def read_file(path: str) -> str:
+        with open(path) as f:
+            return f.read()
+
+    safe_read = protect(read_file, sink="filesystem.read", profile="prod_locked")
+
+    # Blocked: /etc/passwd is in blocklist
+    try:
+        safe_read("/etc/passwd")
+    except ExecutionBlocked as e:
+        print(f"Blocked: {e.decision.human_reason}")
+
+    # Allowed: /workspace is in allowlist
+    content = safe_read("/workspace/data.txt")
+"""
+
+__version__ = "0.1.0"
+__author__ = "MVAR Security"
+__license__ = "Apache-2.0"
+
+from clawzero.contracts import ActionDecision, ActionRequest
+from clawzero.adapters import OpenClawAdapter
+from clawzero.exceptions import (
+    ClawZeroConfigError,
+    ClawZeroError,
+    ClawZeroRuntimeError,
+    ExecutionBlocked,
+    UnsupportedFrameworkError,
+)
+from clawzero.protect import protect
+from clawzero.runtime import MVARRuntime
+from clawzero.witness import (
+    WitnessGenerator,
+    generate_witness,
+    get_witness_generator,
+    set_witness_output_dir,
+)
+
+__all__ = [
+    # Core API
+    "protect",
+    "MVARRuntime",
+    "OpenClawAdapter",
+    # Contracts
+    "ActionRequest",
+    "ActionDecision",
+    # Exceptions
+    "ExecutionBlocked",
+    "ClawZeroError",
+    "ClawZeroConfigError",
+    "ClawZeroRuntimeError",
+    "UnsupportedFrameworkError",
+    # Witness generation
+    "WitnessGenerator",
+    "generate_witness",
+    "get_witness_generator",
+    "set_witness_output_dir",
+    # Adapters (optional import)
+    "adapters",
+]

clawzero/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""
+ClawZero Adapters
+
+Framework-specific adapters for integrating ClawZero with different AI agent systems.
+"""
+
+from clawzero.adapters.openclaw import OpenClawAdapter
+
+__all__ = ["OpenClawAdapter"]

clawzero/adapters/openclaw/__init__.py

@@ -0,0 +1,182 @@
+"""
+OpenClaw adapter for ClawZero.
+
+Integrates OpenClaw tool activity with MVAR enforcement.
+"""
+
+import uuid
+from typing import Callable, Optional
+
+from clawzero.contracts import ActionRequest
+from clawzero.exceptions import ExecutionBlocked
+from clawzero.runtime import MVARRuntime
+
+
+class OpenClawAdapter:
+    """Adapter for integrating ClawZero with OpenClaw runtimes."""
+
+    ADAPTER_VERSION = "0.1.0"
+
+    def __init__(
+        self,
+        profile: str = "dev_balanced",
+        agent_id: Optional[str] = None,
+        session_id: Optional[str] = None,
+    ):
+        self.runtime = MVARRuntime(profile=profile)
+        self.profile = profile
+        self.agent_id = agent_id or "openclaw_agent"
+        self.session_id = session_id
+
+    def wrap_tool(self, tool: Callable, sink_type: Optional[str] = None) -> Callable:
+        """Wrap an OpenClaw tool with MVAR enforcement."""
+        from functools import wraps
+
+        if sink_type is None:
+            sink_type = self._infer_sink_type(tool)
+
+        tool_name = getattr(tool, "__name__", str(tool))
+
+        @wraps(tool)
+        def protected_tool(*args, **kwargs):
+            target = self._extract_target(tool_name, args, kwargs)
+
+            request = ActionRequest(
+                request_id=str(uuid.uuid4()),
+                framework="openclaw",
+                agent_id=self.agent_id,
+                session_id=self.session_id,
+                action_type="tool_call",
+                sink_type=sink_type,
+                tool_name=tool_name,
+                target=target,
+                arguments={"args": args, "kwargs": kwargs},
+                prompt_provenance=self._build_prompt_provenance(),
+                policy_profile=self.profile,
+                metadata={
+                    "adapter": self._build_adapter_metadata(mode="tool_wrap"),
+                },
+            )
+
+            decision = self.runtime.evaluate(request)
+
+            if decision.is_blocked():
+                raise ExecutionBlocked(decision)
+
+            return tool(*args, **kwargs)
+
+        setattr(protected_tool, "__clawzero_protected__", True)
+        setattr(protected_tool, "__clawzero_sink__", sink_type)
+
+        return protected_tool
+
+    def intercept_tool_call(self, event: dict) -> None:
+        """Intercept and enforce an OpenClaw tool-call event."""
+        tool_name = event.get("tool_name", "unknown")
+        arguments = event.get("arguments", {})
+
+        sink_type = self._infer_sink_type_from_name(tool_name)
+        target = self._extract_target_from_event(tool_name, arguments)
+
+        request = ActionRequest(
+            request_id=str(uuid.uuid4()),
+            framework="openclaw",
+            agent_id=self.agent_id,
+            session_id=self.session_id,
+            action_type="tool_call",
+            sink_type=sink_type,
+            tool_name=tool_name,
+            target=target,
+            arguments=arguments,
+            prompt_provenance=self._build_prompt_provenance(),
+            policy_profile=self.profile,
+            metadata={
+                "adapter": self._build_adapter_metadata(mode="event_intercept"),
+            },
+        )
+
+        decision = self.runtime.evaluate(request)
+
+        if decision.is_blocked():
+            raise ExecutionBlocked(decision)
+
+    def _build_prompt_provenance(self) -> dict:
+        """Return canonical OpenClaw provenance for all adapter request paths."""
+        return {
+            "source": "openclaw_tool_call",
+            "adapter_version": self.ADAPTER_VERSION,
+            "framework": "openclaw",
+            "taint_level": "untrusted",
+        }
+
+    def _build_adapter_metadata(self, mode: str) -> dict:
+        """Return canonical adapter metadata for witness emission."""
+        return {
+            "name": "openclaw",
+            "mode": mode,
+            "framework": "openclaw",
+        }
+
+    def _infer_sink_type(self, tool: Callable) -> str:
+        tool_name = getattr(tool, "__name__", "").lower()
+        return self._infer_sink_type_from_name(tool_name)
+
+    def _infer_sink_type_from_name(self, tool_name: str) -> str:
+        tool_name_lower = tool_name.lower()
+
+        if any(x in tool_name_lower for x in ["bash", "shell", "exec", "command", "run"]):
+            return "shell.exec"
+
+        if any(x in tool_name_lower for x in ["read", "open", "load", "cat", "view", "show", "get_file"]):
+            return "filesystem.read"
+
+        if any(x in tool_name_lower for x in ["write", "save", "create", "delete", "remove", "mkdir"]):
+            return "filesystem.write"
+
+        if any(x in tool_name_lower for x in ["http", "request", "fetch", "get", "post", "curl", "wget"]):
+            return "http.request"
+
+        if any(x in tool_name_lower for x in ["env", "cred", "credential", "secret", "key", "token", "password"]):
+            return "credentials.access"
+
+        return "tool.custom"
+
+    def _extract_target(self, tool_name: str, args: tuple, kwargs: dict) -> Optional[str]:
+        if "path" in kwargs:
+            return str(kwargs["path"])
+        if "file" in kwargs:
+            return str(kwargs["file"])
+        if "filename" in kwargs:
+            return str(kwargs["filename"])
+        if "command" in kwargs:
+            return str(kwargs["command"])
+        if "url" in kwargs:
+            return str(kwargs["url"])
+
+        if args:
+            return str(args[0])
+
+        return None
+
+    def _extract_target_from_event(self, tool_name: str, arguments: dict) -> Optional[str]:
+        for key in ["path", "file", "filename", "command", "url", "target"]:
+            if key in arguments:
+                return str(arguments[key])
+
+        if arguments:
+            return str(next(iter(arguments.values())))
+
+        return None
+
+
+def create_openclaw_adapter(
+    profile: str = "dev_balanced",
+    agent_id: Optional[str] = None,
+    session_id: Optional[str] = None,
+) -> OpenClawAdapter:
+    """Convenience constructor for OpenClawAdapter."""
+    return OpenClawAdapter(
+        profile=profile,
+        agent_id=agent_id,
+        session_id=session_id,
+    )

clawzero/cli.py

@@ -0,0 +1,217 @@
+"""ClawZero command line interface.
+
+ClawZero is an in-path enforcement substrate for production agent flows.
+The CLI exposes enforcement-first jobs: demo proof, witness inspection,
+policy audit, and attack replay.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import uuid
+from pathlib import Path
+
+from clawzero.contracts import ActionRequest
+from clawzero.runtime import MVARRuntime
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _run_openclaw_demo(mode: str, scenario: str) -> int:
+    demo_script = _repo_root() / "demo" / "openclaw_attack_demo.py"
+    if not demo_script.exists():
+        print(f"Demo script not found: {demo_script}", file=sys.stderr)
+        return 2
+
+    cmd = [sys.executable, str(demo_script), "--mode", mode, "--scenario", scenario]
+    proc = subprocess.run(cmd, check=False)
+    return proc.returncode
+
+
+def _cmd_demo_openclaw(args: argparse.Namespace) -> int:
+    return _run_openclaw_demo(mode=args.mode, scenario=args.scenario)
+
+
+def _cmd_attack_replay(args: argparse.Namespace) -> int:
+    # Attack replay is intentionally routed through the same enforcement demo.
+    return _run_openclaw_demo(mode="compare", scenario=args.scenario)
+
+
+def _cmd_audit_decision(args: argparse.Namespace) -> int:
+    runtime = MVARRuntime(profile=args.profile)
+
+    taint_markers = [m.strip() for m in args.taint_markers.split(",") if m.strip()]
+    request = ActionRequest(
+        request_id=str(uuid.uuid4()),
+        framework="openclaw",
+        action_type="tool_call",
+        sink_type=args.sink_type,
+        tool_name=args.tool_name,
+        target=args.target,
+        arguments={"command": args.command},
+        prompt_provenance={
+            "source": args.source,
+            "taint_level": args.taint_level,
+            "source_chain": [args.source, "openclaw_tool_call"],
+            "taint_markers": taint_markers,
+        },
+        policy_profile=args.profile,
+        metadata={
+            "adapter": {
+                "name": "openclaw",
+                "mode": "tool_wrap",
+                "framework": "openclaw",
+            }
+        },
+    )
+
+    decision = runtime.evaluate(request)
+
+    print("ClawZero Enforcement Audit")
+    print("-" * 32)
+    print(f"decision   : {decision.decision}")
+    print(f"reason     : {decision.reason_code}")
+    print(f"human      : {decision.human_reason}")
+    print(f"sink       : {decision.sink_type}")
+    print(f"target     : {decision.target}")
+    print(f"policy_id  : {decision.policy_id}")
+    print(f"engine     : {decision.engine}")
+    if runtime.last_witness:
+        print(f"witness_id : {runtime.last_witness.get('witness_id')}")
+    return 0
+
+
+def _cmd_witness_show(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    if not path.exists():
+        print(f"Witness file not found: {path}", file=sys.stderr)
+        return 2
+
+    witness = json.loads(path.read_text(encoding="utf-8"))
+    print(json.dumps(witness, indent=2))
+    return 0
+
+
+def _cmd_witness_verify(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    if not path.exists():
+        print(f"Witness file not found: {path}", file=sys.stderr)
+        return 2
+
+    witness = json.loads(path.read_text(encoding="utf-8"))
+    required = {
+        "timestamp",
+        "agent_runtime",
+        "sink_type",
+        "target",
+        "decision",
+        "reason_code",
+        "policy_id",
+        "engine",
+        "provenance",
+        "adapter",
+        "witness_signature",
+    }
+    missing = sorted(required.difference(witness.keys()))
+    if missing:
+        print("invalid witness")
+        print(f"missing keys: {', '.join(missing)}")
+        return 1
+
+    print("witness valid")
+    print(f"decision: {witness.get('decision')}")
+    print(f"policy : {witness.get('policy_id')}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="clawzero",
+        description=(
+            "ClawZero: deterministic in-path execution boundary for OpenClaw agent flows."
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    demo = subparsers.add_parser(
+        "demo",
+        help="Run enforcement proof demos (same input, different boundary).",
+    )
+    demo_sub = demo.add_subparsers(dest="demo_command", required=True)
+    demo_openclaw = demo_sub.add_parser(
+        "openclaw",
+        help="Run OpenClaw demo through standard vs MVAR-protected paths.",
+    )
+    demo_openclaw.add_argument("--mode", choices=["standard", "mvar", "compare"], default="compare")
+    demo_openclaw.add_argument(
+        "--scenario", choices=["shell", "credentials", "benign"], default="shell"
+    )
+    demo_openclaw.set_defaults(func=_cmd_demo_openclaw)
+
+    witness = subparsers.add_parser(
+        "witness",
+        help="Inspect and validate signed witness artifacts from enforcement decisions.",
+    )
+    witness_sub = witness.add_subparsers(dest="witness_command", required=True)
+    witness_show = witness_sub.add_parser("show", help="Print a witness JSON artifact.")
+    witness_show.add_argument("--file", required=True, help="Path to witness JSON file.")
+    witness_show.set_defaults(func=_cmd_witness_show)
+
+    witness_verify = witness_sub.add_parser(
+        "verify", help="Verify required canonical fields in a witness artifact."
+    )
+    witness_verify.add_argument("--file", required=True, help="Path to witness JSON file.")
+    witness_verify.set_defaults(func=_cmd_witness_verify)
+
+    audit = subparsers.add_parser(
+        "audit",
+        help="Audit deterministic policy enforcement for a specific sink request.",
+    )
+    audit_sub = audit.add_subparsers(dest="audit_command", required=True)
+    audit_decision = audit_sub.add_parser(
+        "decision", help="Evaluate a single request through the active MVAR runtime."
+    )
+    audit_decision.add_argument("--profile", default="prod_locked")
+    audit_decision.add_argument("--sink-type", required=True)
+    audit_decision.add_argument("--target", required=True)
+    audit_decision.add_argument("--tool-name", default="tool_call")
+    audit_decision.add_argument("--command", default="")
+    audit_decision.add_argument("--source", default="external_document")
+    audit_decision.add_argument("--taint-level", default="untrusted")
+    audit_decision.add_argument("--taint-markers", default="prompt_injection,external_content")
+    audit_decision.set_defaults(func=_cmd_audit_decision)
+
+    attack = subparsers.add_parser(
+        "attack",
+        help="Replay known attack scenarios to prove sink-boundary enforcement.",
+    )
+    attack_sub = attack.add_subparsers(dest="attack_command", required=True)
+    attack_replay = attack_sub.add_parser(
+        "replay",
+        help="Run compare-mode attack replay (standard compromised vs MVAR blocked).",
+    )
+    attack_replay.add_argument(
+        "--scenario", choices=["shell", "credentials", "benign"], default="shell"
+    )
+    attack_replay.set_defaults(func=_cmd_attack_replay)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    func = getattr(args, "func", None)
+    if func is None:
+        parser.print_help()
+        return 2
+    return int(func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clawzero/contracts.py

@@ -0,0 +1,63 @@
+"""
+ClawZero contracts.
+
+Data contracts for execution-boundary requests and decisions.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class ActionRequest:
+    """A request entering the execution boundary."""
+
+    request_id: str
+    framework: str
+
+    agent_id: Optional[str] = None
+    session_id: Optional[str] = None
+
+    action_type: str = "tool_call"
+    sink_type: str = "tool.custom"
+
+    tool_name: Optional[str] = None
+    target: Optional[str] = None
+
+    arguments: dict[str, Any] = field(default_factory=dict)
+    prompt_provenance: dict[str, Any] = field(default_factory=dict)
+    conversation_context: dict[str, Any] = field(default_factory=dict)
+
+    policy_profile: str = "dev_balanced"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ActionDecision:
+    """Deterministic policy decision emitted by the runtime."""
+
+    request_id: str
+    decision: str
+    reason_code: str
+    human_reason: str
+
+    sink_type: str
+    target: Optional[str]
+    policy_profile: str
+
+    engine: str = "embedded-policy-v0.1"
+    policy_id: str = "mvar-embedded.v0.1"
+
+    trust_level: Optional[str] = None
+    witness_id: Optional[str] = None
+
+    annotations: dict[str, Any] = field(default_factory=dict)
+
+    def is_blocked(self) -> bool:
+        return self.decision == "block"
+
+    def is_allowed(self) -> bool:
+        return self.decision == "allow"
+
+    def is_annotated(self) -> bool:
+        return self.decision == "annotate"

clawzero/exceptions.py

@@ -0,0 +1,34 @@
+"""ClawZero exceptions."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from clawzero.contracts import ActionDecision
+
+
+class ClawZeroError(Exception):
+    """Base exception for all ClawZero errors."""
+
+
+class ExecutionBlocked(ClawZeroError):
+    """Raised when MVAR blocks an action from reaching a protected sink."""
+
+    def __init__(self, decision: "ActionDecision"):
+        self.decision = decision
+        message = f"MVAR blocked: {decision.reason_code} — {decision.human_reason}"
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"MVAR blocked: {self.decision.reason_code} — {self.decision.human_reason}"
+
+
+class ClawZeroConfigError(ClawZeroError):
+    """Raised when ClawZero configuration is invalid or missing."""
+
+
+class ClawZeroRuntimeError(ClawZeroError):
+    """Raised when ClawZero encounters an unexpected runtime error."""
+
+
+class UnsupportedFrameworkError(ClawZeroError):
+    """Raised when attempting to protect a tool from an unsupported framework."""

clawzero/policies/__init__.py

@@ -0,0 +1,5 @@
+"""Policy definitions for deterministic sink enforcement."""
+
+from clawzero.policies.profiles import PROFILES
+
+__all__ = ["PROFILES"]

clawzero/policies/profiles.py

@@ -0,0 +1,25 @@
+"""Embedded policy profile metadata for documentation and tooling."""
+
+PROFILES = {
+    "dev_balanced": {
+        "shell.exec": "block",
+        "filesystem.read": "profile_sensitive",
+        "http.request": "allow",
+        "credentials.access": "block",
+        "tool.custom": "allow",
+    },
+    "dev_strict": {
+        "shell.exec": "block",
+        "filesystem.read": "allow /workspace only",
+        "http.request": "block",
+        "credentials.access": "block",
+        "tool.custom": "annotate",
+    },
+    "prod_locked": {
+        "shell.exec": "block",
+        "filesystem.read": "allow /workspace/project only",
+        "http.request": "allow localhost only",
+        "credentials.access": "block",
+        "tool.custom": "allow",
+    },
+}