kaizen-security 0.1.0__tar.gz

kaizen_security-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: kaizen-security
+Version: 0.1.0
+Summary: Pluggable enforcement for AI agent actions. Inspect every tool call and block known-bad.
+Author: Kaizen Security
+License: Apache-2.0
+Project-URL: Homepage, https://getkaizen.io
+Project-URL: Documentation, https://docs.getkaizen.io
+Keywords: ai,agents,security,mcp,guardrails
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest<9.0,>=8.0; extra == "test"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == "openai-agents"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == "langchain"
+Provides-Extra: opentelemetry
+Requires-Dist: opentelemetry-api>=1.20; extra == "opentelemetry"
+
+# kaizen-security
+
+Pluggable enforcement for AI agent actions. Inspect every tool call, skill load, or outbound connection, and block the known-bad before it reaches your data. Zero runtime dependencies.
+
+## Install
+
+```bash
+pip install kaizen-security
+```
+
+## Quickstart
+
+```python
+from kaizen_security import Kaizen
+
+kz = Kaizen(api_key="kz_live_...")          # syncs policy from the control plane
+
+verdict = kz.inspect(tool="clawhub2", publisher="hightower6eu", target="91.92.242.30")
+if verdict.blocked:
+    print(verdict.reason)                    # blocked by policy: blacklisted publisher, ...
+    for f in verdict.evidence:
+        print(f.kind, f.value)
+```
+
+Raise on a block instead of branching:
+
+```python
+from kaizen_security import KaizenBlocked
+
+try:
+    kz.enforce(tool="clawhub2", publisher="hightower6eu")
+except KaizenBlocked as e:
+    handle(e.verdict)
+```
+
+Wrap a tool function:
+
+```python
+@kz.guard
+def call_tool(name, **kwargs):
+    ...
+```
+
+## Run it fully local, no account
+
+```python
+from kaizen_security import Kaizen, Policy
+
+policy = Policy(mode="blocklist", rules={
+    "publishers": ["hightower6eu"],
+    "ips": ["91.92.242.30"],
+    "skill_patterns": [r"^clawhub[0-9]*$"],
+})
+kz = Kaizen(policies=[policy], report=False)
+```
+
+## The contract
+
+`inspect(action) -> Verdict(decision, reason, evidence)` where `decision` is `allow` or `block`. Enforcement runs locally for low latency. When an `api_key` is set, the client syncs policy from the control plane and reports verdicts back for the dashboard, fire and forget so it never adds latency.
+
+## Modes
+
+- `blocklist`: block on a match against blacklisted publishers, IPs, domains, skill patterns, or hashes.
+- `allowlist`: allow only approved publishers or tools, block the rest.
+- `correlation`: flag a risky session sequence, for example a sensitive read followed by an outbound connect.

kaizen_security-0.1.0/README.md

@@ -0,0 +1,65 @@
+# kaizen-security
+
+Pluggable enforcement for AI agent actions. Inspect every tool call, skill load, or outbound connection, and block the known-bad before it reaches your data. Zero runtime dependencies.
+
+## Install
+
+```bash
+pip install kaizen-security
+```
+
+## Quickstart
+
+```python
+from kaizen_security import Kaizen
+
+kz = Kaizen(api_key="kz_live_...")          # syncs policy from the control plane
+
+verdict = kz.inspect(tool="clawhub2", publisher="hightower6eu", target="91.92.242.30")
+if verdict.blocked:
+    print(verdict.reason)                    # blocked by policy: blacklisted publisher, ...
+    for f in verdict.evidence:
+        print(f.kind, f.value)
+```
+
+Raise on a block instead of branching:
+
+```python
+from kaizen_security import KaizenBlocked
+
+try:
+    kz.enforce(tool="clawhub2", publisher="hightower6eu")
+except KaizenBlocked as e:
+    handle(e.verdict)
+```
+
+Wrap a tool function:
+
+```python
+@kz.guard
+def call_tool(name, **kwargs):
+    ...
+```
+
+## Run it fully local, no account
+
+```python
+from kaizen_security import Kaizen, Policy
+
+policy = Policy(mode="blocklist", rules={
+    "publishers": ["hightower6eu"],
+    "ips": ["91.92.242.30"],
+    "skill_patterns": [r"^clawhub[0-9]*$"],
+})
+kz = Kaizen(policies=[policy], report=False)
+```
+
+## The contract
+
+`inspect(action) -> Verdict(decision, reason, evidence)` where `decision` is `allow` or `block`. Enforcement runs locally for low latency. When an `api_key` is set, the client syncs policy from the control plane and reports verdicts back for the dashboard, fire and forget so it never adds latency.
+
+## Modes
+
+- `blocklist`: block on a match against blacklisted publishers, IPs, domains, skill patterns, or hashes.
+- `allowlist`: allow only approved publishers or tools, block the rest.
+- `correlation`: flag a risky session sequence, for example a sensitive read followed by an outbound connect.

kaizen_security-0.1.0/kaizen_security/__init__.py

@@ -0,0 +1,5 @@
+from .client import Kaizen, KaizenBlocked
+from .models import Action, Finding, Policy, Verdict
+
+__all__ = ["Kaizen", "KaizenBlocked", "Action", "Finding", "Policy", "Verdict"]
+__version__ = "0.1.0"

kaizen_security-0.1.0/kaizen_security/client.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import functools
+import threading
+import warnings
+from collections import deque
+from typing import Optional
+
+from . import engine
+from .models import Action, Finding, Policy, Verdict
+from .report import Reporter
+
+
+class KaizenBlocked(Exception):
+    def __init__(self, verdict: Verdict):
+        self.verdict = verdict
+        super().__init__(verdict.reason)
+
+
+class Kaizen:
+    """The data plane client. Enforces policy locally for low latency, and
+    reports verdicts to the control plane for the dashboard.
+
+        kz = Kaizen(api_key="kz_live_...")
+        v = kz.inspect(tool="clawhub2", publisher="hightower6eu")
+        if v.blocked: ...
+
+    fail_open defaults to False: if our own evaluation errors, we block. This is
+    a security control, so the safe failure is to deny. Set fail_open=True only
+    if you accept that our bugs become a bypass, and watch your logs.
+    """
+
+    def __init__(
+        self,
+        api_key: str = "",
+        base_url: str = "https://api.getkaizen.io",
+        policies: Optional[list[Policy]] = None,
+        agent: str = "default",
+        fail_open: bool = False,
+        report: bool = True,
+        sync: bool = True,
+        on_verdict=None,
+    ):
+        self.api_key = api_key
+        self.base_url = self._check_url(base_url.rstrip("/"))
+        self.policies = list(policies) if policies else []
+        self.agent = agent
+        self.fail_open = fail_open
+        self._session: deque[Action] = deque(maxlen=20)
+        self._lock = threading.Lock()
+        self._report = report
+        # the reporter exists whenever there is an api_key (it also fetches policy);
+        # the report flag only controls whether we send verdicts back.
+        self._reporter = Reporter(self.base_url, api_key) if api_key else None
+        # optional callback fired after every verdict (used by the OTel exporter)
+        self._on_verdict = on_verdict
+        if sync and api_key and not self.policies:
+            self._sync_policies()
+
+    @staticmethod
+    def _check_url(url: str) -> str:
+        if url.startswith("http://") and not url.startswith(("http://localhost", "http://127.0.0.1")):
+            warnings.warn(
+                "Kaizen base_url is http://, the API key and action data would travel in cleartext. Use https.",
+                stacklevel=3,
+            )
+        return url
+
+    def _sync_policies(self) -> None:
+        if not self._reporter:
+            return
+        fetched = self._reporter.get_policies(self.agent)
+        if fetched is not None:
+            self.policies = fetched
+
+    def inspect(self, action: Optional[Action] = None, **kw) -> Verdict:
+        a = action if action is not None else Action(**kw)
+        try:
+            v = engine.evaluate(a, self.policies)
+        except Exception:
+            v = Verdict("allow" if self.fail_open else "block", "engine error, failed " + ("open" if self.fail_open else "closed"))
+
+        # correlation may only escalate an allow to a block, never downgrade a block
+        if v.allowed:
+            try:
+                v = self._correlate(a, v)
+            except Exception:
+                if not self.fail_open:
+                    v = Verdict("block", "correlation error, failed closed")
+
+        with self._lock:
+            self._session.append(a)
+        if self._reporter and self._report:
+            self._reporter.send(self.agent, a, v)
+        if self._on_verdict:
+            try:
+                self._on_verdict(v, a)
+            except Exception:
+                pass
+        return v
+
+    def enforce(self, action: Optional[Action] = None, **kw) -> Verdict:
+        v = self.inspect(action, **kw)
+        if v.blocked:
+            raise KaizenBlocked(v)
+        return v
+
+    def _correlate(self, a: Action, v: Verdict) -> Verdict:
+        # v1 session rule: a sensitive read earlier, then an outbound connect now.
+        for p in self.policies:
+            if not p.enabled or p.mode != "correlation":
+                continue
+            if (p.rules or {}).get("risky_sequence") == "read_then_connect" and a.kind == "connect":
+                with self._lock:
+                    prior = list(self._session)
+                if any(prev.kind == "file" and (prev.metadata or {}).get("sensitive") for prev in prior):
+                    return Verdict(
+                        "block",
+                        "blocked by correlation: sensitive read then outbound connect",
+                        [Finding("risky sequence", "sensitive read then connect", "correlation")],
+                    )
+        return v
+
+    def guard(self, fn=None, *, tool: Optional[str] = None, kind: str = "tool_call"):
+        """Decorator that inspects a tool call before running it.
+
+        The inspected tool name defaults to the function name; pass tool= to
+        match the name your agent actually invokes. We do not serialize the
+        call arguments into the action, to avoid shipping secrets.
+        """
+        def deco(func):
+            name = tool or getattr(func, "__name__", "tool")
+
+            @functools.wraps(func)
+            def wrapper(*args, **kwargs):
+                self.enforce(Action(kind=kind, tool=name))
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return deco(fn) if callable(fn) else deco

kaizen_security-0.1.0/kaizen_security/engine.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import ipaddress
+import re
+import unicodedata
+from typing import Optional
+from urllib.parse import urlparse
+
+from .models import Action, Finding, Policy, Verdict
+
+# zero-width and format characters used to disguise lookalike strings
+_ZERO_WIDTH = dict.fromkeys(map(ord, "​‌‍⁠"), None)
+
+_MAX_PATTERN = 200   # cap remote regex length to bound catastrophic backtracking
+_MAX_TOOL = 512      # cap the string we match against
+
+
+def _norm(s: Optional[str]) -> Optional[str]:
+    if not isinstance(s, str):
+        return s
+    return unicodedata.normalize("NFKC", s).translate(_ZERO_WIDTH).strip().lower()
+
+
+def _as_ip(host: str):
+    """Parse a host as an IP, tolerating integer form. Returns None if not an IP."""
+    try:
+        return ipaddress.ip_address(host)
+    except ValueError:
+        pass
+    if host.isdigit():
+        try:
+            return ipaddress.ip_address(int(host))
+        except ValueError:
+            return None
+    return None
+
+
+def _host_of(target: str):
+    """Pull the host out of a URL or host:port, return (ip_or_none, host_lower)."""
+    t = target.strip()
+    if "://" in t:
+        t = urlparse(t).hostname or t
+    else:
+        t = t.split("/", 1)[0]
+    if t.startswith("[") and "]" in t:                 # IPv6 with brackets
+        host = t[1 : t.index("]")]
+    elif t.count(":") == 1:                            # host:port
+        host = t.rsplit(":", 1)[0]
+    else:
+        host = t
+    host = host.rstrip(".").lower()
+    return _as_ip(host), host
+
+
+def _networks(values) -> list:
+    nets = []
+    for v in values or []:
+        try:
+            nets.append(ipaddress.ip_network(str(v).strip(), strict=False))
+        except ValueError:
+            continue
+    return nets
+
+
+def _domain_hit(host: str, domains) -> Optional[str]:
+    h = host.rstrip(".").lower()
+    for d in domains or []:
+        dn = (_norm(str(d)) or "").rstrip(".")
+        if dn and (h == dn or h.endswith("." + dn)):  # match the domain and any subdomain
+            return dn
+    return None
+
+
+def evaluate(action: Action, policies: list[Policy]) -> Verdict:
+    """Stateless evaluation of allowlist and blocklist policies.
+
+    Session-aware correlation lives in the client, which holds the session.
+    Defensive throughout: a malformed remote policy must not throw, because the
+    client's outer handler would otherwise fail the whole evaluation open.
+    """
+    findings: list[Finding] = []
+    for p in policies:
+        if not p.enabled:
+            continue
+        rules = p.rules or {}
+        if p.mode == "blocklist":
+            findings += _blocklist(action, rules)
+        elif p.mode == "allowlist":
+            f = _allowlist(action, rules)
+            if f:
+                findings.append(f)
+    if findings:
+        kinds = ", ".join(sorted({f.kind for f in findings}))
+        return Verdict("block", f"blocked by policy: {kinds}", findings)
+    return Verdict("allow", "no policy matched")
+
+
+def _blocklist(a: Action, rules: dict) -> list[Finding]:
+    out: list[Finding] = []
+
+    pub = _norm(a.publisher)
+    if pub and pub in {_norm(x) for x in (rules.get("publishers") or [])}:
+        out.append(Finding("blacklisted publisher", a.publisher, "blocklist"))
+
+    if a.target:
+        ip, host = _host_of(a.target)
+        if ip is not None:
+            if any(ip in net for net in _networks(rules.get("ips"))):
+                out.append(Finding("known-bad address", str(ip), "blocklist"))
+        else:
+            hit = _domain_hit(host, rules.get("domains"))
+            if hit:
+                out.append(Finding("malicious domain", host, "blocklist"))
+
+    if a.hash:
+        h = a.hash.strip().lower()
+        if h in {str(x).strip().lower() for x in (rules.get("hashes") or [])}:
+            out.append(Finding("known-bad hash", a.hash[:16] + "…", "blocklist"))
+
+    if a.tool:
+        tool = a.tool[:_MAX_TOOL]
+        for pat in (rules.get("skill_patterns") or []):
+            if not isinstance(pat, str) or len(pat) > _MAX_PATTERN:
+                continue
+            try:
+                if re.fullmatch(pat, tool):
+                    out.append(Finding("malicious skill pattern", a.tool, "blocklist"))
+                    break
+            except re.error:
+                continue
+    return out
+
+
+def _allowlist(a: Action, rules: dict) -> Optional[Finding]:
+    """Default-deny. Every dimension the policy constrains must match (AND).
+
+    Policy validation guarantees at least one of publishers or tools is set, so
+    an empty allowlist can never silently block everything.
+    """
+    allowed_pubs = {_norm(x) for x in (rules.get("publishers") or [])}
+    allowed_tools = {_norm(x) for x in (rules.get("tools") or [])}
+
+    if allowed_pubs and _norm(a.publisher) not in allowed_pubs:
+        return Finding("publisher not on the allowlist", a.publisher or "none", "allowlist")
+    if allowed_tools and _norm(a.tool) not in allowed_tools:
+        return Finding("tool not on the allowlist", a.tool or "none", "allowlist")
+    return None

kaizen_security-0.1.0/kaizen_security/integrations/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters that attach Kaizen to existing agent runtimes."""

kaizen_security-0.1.0/kaizen_security/integrations/langchain.py

@@ -0,0 +1,62 @@
+"""Attach Kaizen to a LangChain / LangGraph agent.
+
+Observe every tool call with the callback handler:
+
+    from kaizen_security import Kaizen
+    from kaizen_security.integrations.langchain import KaizenCallbackHandler
+
+    kz = Kaizen(api_key="kz_live_...", agent="support-bot")
+    agent.invoke({"input": "..."}, config={"callbacks": [KaizenCallbackHandler(kz)]})
+
+The callback is observe-only: LangChain swallows exceptions raised inside
+callbacks, so it cannot block a tool. To BLOCK, wrap the tool instead:
+
+    from kaizen_security.integrations.langchain import guard_tool
+    safe_tool = guard_tool(kz, my_tool)
+
+langchain is an optional dependency; this module imports it lazily.
+"""
+from __future__ import annotations
+
+from ..models import Action
+
+try:  # modern LangChain
+    from langchain_core.callbacks import BaseCallbackHandler as _Base
+except Exception:  # pragma: no cover
+    try:  # older LangChain
+        from langchain.callbacks.base import BaseCallbackHandler as _Base
+    except Exception:
+        _Base = object
+
+
+class KaizenCallbackHandler(_Base):
+    """Reports every tool call to Kaizen so the Observer learns the agent's
+    behavior and flags deviations. Observe-only (see guard_tool to block)."""
+
+    def __init__(self, kaizen):
+        self.kaizen = kaizen
+
+    def on_tool_start(self, serialized, input_str, **kwargs):
+        name = (serialized or {}).get("name") or "tool"
+        self.kaizen.inspect(Action(kind="tool_call", tool=name, metadata={"input": input_str}))
+
+
+def guard_tool(kaizen, tool, enforce: bool = True):
+    """Wrap a LangChain tool so Kaizen inspects each call. With enforce (default),
+    a blocked call returns a refusal string instead of executing the tool."""
+    from langchain_core.tools import StructuredTool
+
+    name = getattr(tool, "name", None) or "tool"
+
+    def _wrapped(**kwargs):
+        verdict = kaizen.inspect(Action(kind="tool_call", tool=name, metadata={"input": kwargs}))
+        if enforce and verdict.blocked:
+            return f"Blocked by Kaizen: {verdict.reason}"
+        return tool.invoke(kwargs)
+
+    return StructuredTool.from_function(
+        func=_wrapped,
+        name=name,
+        description=getattr(tool, "description", "") or "",
+        args_schema=getattr(tool, "args_schema", None),
+    )

kaizen_security-0.1.0/kaizen_security/integrations/openai_agents.py

@@ -0,0 +1,57 @@
+"""Attach Kaizen to an OpenAI Agents SDK agent in one line.
+
+    from agents import Agent, Runner
+    from kaizen_security import Kaizen
+    from kaizen_security.integrations.openai_agents import KaizenHooks
+
+    kz = Kaizen(api_key="kz_live_...", agent="support-bot")
+    await Runner.run(agent, "do the thing", hooks=KaizenHooks(kz))
+
+Every tool the agent calls flows to Kaizen: it is inspected against policy and
+reported, so the isolated Observer learns the agent's behavior and flags
+deviations. Observe-only by default; with enforce=True a blocked tool is stopped
+before it runs (via the SDK's tool-rejection path, falling back to raising).
+
+Importing this module does not require openai-agents to be installed; KaizenHooks
+only needs it at runtime when you actually run an agent.
+"""
+from __future__ import annotations
+
+from ..client import KaizenBlocked
+from ..models import Action
+
+try:  # the base class is provided by openai-agents when present
+    from agents import RunHooks as _Base
+except Exception:  # pragma: no cover - openai-agents optional
+    _Base = object
+
+
+def _tool_name(tool) -> str:
+    return getattr(tool, "name", None) or getattr(tool, "__name__", None) or "tool"
+
+
+def _tool_args(context):
+    for attr in ("tool_input", "tool_arguments"):
+        v = getattr(context, attr, None)
+        if v is not None:
+            return v
+    return None
+
+
+class KaizenHooks(_Base):
+    """RunHooks that route every tool call through Kaizen."""
+
+    def __init__(self, kaizen, enforce: bool = False):
+        self.kaizen = kaizen
+        self.enforce = enforce
+
+    async def on_tool_start(self, context, agent, tool):
+        action = Action(kind="tool_call", tool=_tool_name(tool), metadata={"arguments": _tool_args(context)})
+        verdict = self.kaizen.inspect(action)
+        if self.enforce and verdict.blocked:
+            reject = getattr(context, "reject_tool", None)
+            if callable(reject):
+                reject(verdict.reason)  # clean: tool never executes
+            else:
+                raise KaizenBlocked(verdict)
+        return None

kaizen_security-0.1.0/kaizen_security/integrations/otel.py

@@ -0,0 +1,39 @@
+"""Emit an OpenTelemetry span for each Kaizen verdict.
+
+    from kaizen_security import Kaizen
+    from kaizen_security.integrations.otel import record_verdict
+
+    kz = Kaizen(api_key="kz_live_...", on_verdict=record_verdict)
+
+Every inspect() then appears in your traces as a `kaizen.inspect` span carrying
+the decision, reason, tool, and target. Blocked verdicts mark the span as an
+error, so they surface in Datadog, Grafana, Honeycomb, or any OTel backend with
+no per-vendor code. opentelemetry is an optional dependency.
+"""
+from __future__ import annotations
+
+try:
+    from opentelemetry import trace as _trace
+except Exception:  # pragma: no cover - opentelemetry optional
+    _trace = None
+
+
+def record_verdict(verdict, action=None):
+    if _trace is None:
+        return
+    tracer = _trace.get_tracer("kaizen-security")
+    with tracer.start_as_current_span("kaizen.inspect") as span:
+        span.set_attribute("kaizen.decision", verdict.decision)
+        if getattr(verdict, "reason", None):
+            span.set_attribute("kaizen.reason", verdict.reason)
+        if action is not None:
+            if action.kind:
+                span.set_attribute("kaizen.kind", action.kind)
+            if action.tool:
+                span.set_attribute("kaizen.tool", action.tool)
+            if getattr(action, "publisher", None):
+                span.set_attribute("kaizen.publisher", action.publisher)
+            if getattr(action, "target", None):
+                span.set_attribute("kaizen.target", action.target)
+        if verdict.blocked:
+            span.set_status(_trace.Status(_trace.StatusCode.ERROR, verdict.reason or "blocked"))