agent-guard-python 0.2.1__cp310-abi3-win_amd64.whl

agent_guard/openai.py

@@ -0,0 +1,87 @@
+from typing import Any, Callable, Optional
+
+from ._agent_guard import Guard
+from .adapters import (
+    build_security_error,
+    dispatch_via_run,
+    ensure_verified_policy,
+    handle_execute_result,
+    has_runtime_api,
+    prepare_payload,
+    resolve_mode,
+)
+
+
+def wrap_openai_tool(
+    guard: Guard,
+    handler: Callable[[Any], Any],
+    *,
+    tool: str,
+    mode: str = "check",
+    trust_level: str = "untrusted",
+    agent_id: Optional[str] = None,
+    actor: Optional[str] = None,
+    result_mapper: Optional[Callable[[Any, Any], Any]] = None,
+    payload_mapper: Optional[Callable[[Any], str]] = None,
+):
+    """
+    Wrap an OpenAI-style tool handler with agent-guard checks.
+
+    The wrapped callable accepts the original handler input and dispatches
+    according to ``mode``:
+
+    - ``"enforce"`` — always sandbox the call via ``Guard.execute``.
+    - ``"check"``   — always go through ``Guard.check`` (policy-only). The
+      original handler runs in-process when allowed. Fail-closed on invalid
+      policy signatures.
+    - ``"auto"`` — for shell-like tools, behave like ``enforce``. For non-shell
+      tools, dispatch through the unified ``Guard.run`` runtime API when the
+      binding exposes it. The ``RuntimeOutcome::Handoff`` variant means the
+      handler runs in-process and the adapter then calls
+      ``Guard.report_handoff_result`` to close the audit loop. When the binding
+      does not expose ``run`` (older builds), ``auto`` for non-shell tools
+      degrades to ``check`` semantics.
+    """
+    if not callable(handler):
+        raise TypeError("wrap_openai_tool requires a callable handler")
+
+    resolved_mode = resolve_mode(tool, mode)
+
+    if resolved_mode == "run" and not has_runtime_api(guard):
+        resolved_mode = "check"
+
+    guard_options = {
+        "agent_id": agent_id,
+        "actor": actor,
+        "trust_level": trust_level,
+    }
+
+    def wrapped(input_data: Any, *args, **kwargs):
+        payload = payload_mapper(input_data) if callable(payload_mapper) else prepare_payload(tool, input_data)
+
+        if resolved_mode == "enforce":
+            result = guard.execute(tool=tool, payload=payload, **guard_options)
+            return handle_execute_result(
+                result,
+                result_mapper=result_mapper,
+                original_input=input_data,
+            )
+
+        if resolved_mode == "run":
+            return dispatch_via_run(
+                guard,
+                tool=tool,
+                payload=payload,
+                guard_options=guard_options,
+                handler=handler,
+                handler_args=(input_data, *args),
+                handler_kwargs=kwargs,
+            )
+
+        decision = guard.check(tool=tool, payload=payload, **guard_options)
+        if decision.outcome != "allow":
+            raise build_security_error(decision)
+        ensure_verified_policy(decision)
+        return handler(input_data, *args, **kwargs)
+
+    return wrapped

agent_guard_python-0.2.1.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: agent-guard-python
+Version: 0.2.1
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Security
+Summary: Outbound change control for AI agents — gate shell, file-write and HTTP side effects before they happen
+Keywords: security,sandbox,policy,agent,audit
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/XuebinMa/agent-guard/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/XuebinMa/agent-guard
+Project-URL: Repository, https://github.com/XuebinMa/agent-guard
+
+# agent-guard-python
+
+> **Python bindings for execution control at the agent side-effect boundary.**
+
+This package provides Python bindings for `agent-guard`, giving Python hosts a pre-execution decision layer before agent tool calls turn into shell commands or other side effects.
+
+---
+
+## 🚀 Quick Start (Python Adapters)
+
+> **Status**: The Python wrapper layer is a **beta adapter surface**. The clearest current proof point is still shell-first execution control, and Node remains the most mature integration path in the repository.
+
+Integrate `agent-guard` into your existing LangChain tools with a policy gate in front of the original tool:
+
+```python
+from agent_guard import Guard, wrap_langchain_tool
+
+# 1. Initialize the Guard with your security policy
+guard = Guard.from_yaml_file("policy.yaml")
+
+# 2. Secure your existing tools
+bash_tool = ShellTool() # Your original tool
+secured_tool = wrap_langchain_tool(guard, bash_tool, agent_id="researcher")
+
+# 3. Use the tool as normal - agent-guard handles the rest!
+secured_tool.run("ls -la")
+```
+
+OpenAI-style handler wrapping is also available:
+
+```python
+from agent_guard import Guard, wrap_openai_tool, AgentGuardDeniedError
+
+guard = Guard.from_yaml_file("policy.yaml")
+
+guarded_handler = wrap_openai_tool(
+    guard,
+    lambda input_data: {"ok": True, "query": input_data["query"]},
+    tool="web_search",
+    mode="check",
+    trust_level="trusted",
+)
+
+try:
+    print(guarded_handler({"query": "agent-guard"}))
+except AgentGuardDeniedError as error:
+    print("blocked", error.code)
+```
+
+---
+
+## ✨ Features
+
+- 🛡️ **Pre-execution policy decisions**: Put allow/deny/ask checks in front of Python tool handlers.
+- 💻 **Shell-first execution control**: The strongest current execution path is still shell / Bash style tooling.
+- ⚠️ **Typed adapter errors**: Distinct deny, ask-required, and execution failure exceptions.
+- 📜 **Signed receipts**: Optional cryptographic proof of execution when you need deeper verification.
+- 🔏 **Signed policy loading**: Optional detached-signature verification for `policy.yaml`.
+- 📊 **Auditing support**: JSONL logs and metrics integration for operator-visible outcomes.
+
+Current boundary note:
+
+- non-shell tools are most often a `check`-style policy gate first
+- shell-style execution remains the clearest current enforcement proof point
+- Python is an active adapter surface, but still below the current Node path in maturity
+- `Guard.execute()` / `Guard.run()` use the SDK default sandbox selection, or accept an explicit `backend=` keyword (`"none"`, `"linux-seccomp"`, `"linux-landlock"`, `"macos-seatbelt"`, `"windows-job-object"`, `"windows-appcontainer"`); a backend that is not compiled into the module or not functional on the host resolves truthfully to `"none"`, and an unknown name raises
+- to get real isolation through `backend=`, build the module with the matching feature forwarded, e.g. `maturin develop --features extension-module,seccomp` (requires libseccomp on Linux); the default build carries no sandbox feature
+- if the default sandbox diagnosis falls back to `NoopSandbox`, the policy gate still runs, but OS-level isolation is not equivalent
+
+---
+
+## 🔧 Installation
+
+Version `0.2.0` is not on PyPI yet. Install it from a repository checkout
+(requires Python and a Rust toolchain):
+
+```bash
+python -m pip install ./crates/agent-guard-python
+```
+
+After the synchronized release, the distribution name will be
+`agent-guard-python`; the import name remains `agent_guard`:
+
+```python
+from agent_guard import Guard
+```
+
+For local development in this repository:
+
+```bash
+cd crates/agent-guard-python
+maturin develop --features extension-module
+pytest tests -v
+```
+
+---
+
+## 📺 Demos
+
+Check the `examples/` directory for full usage scenarios:
+- `demo_langchain.py`: Comprehensive 3-line integration demo.
+- `provenance_receipt.py`: Cryptographic verification example.
+

agent_guard_python-0.2.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+agent_guard/__init__.py,sha256=7grpLwVmtmgCAd0rc7rwSga9WPBo7kz8baPwG5a01yw,965
+agent_guard/_agent_guard.pyd,sha256=omYKPLudWoDAUgrItd-UasbZC2l4tv3t2yDG_uzOvYo,10195456
+agent_guard/adapters.py,sha256=OHPzHlIVNmQJI0mz5jNqfKar6-vjeU1HRHkxToRWPw4,16270
+agent_guard/langchain.py,sha256=Nc_E8AxG0Or_1xwq45h_kWZknodYeZlZcTGg4QOcVS0,5888
+agent_guard/openai.py,sha256=X6tpxWwSaVIPfb9dMMpFCcG0osieLvoH0in2a7nurAo,3054
+agent_guard_python-0.2.1.dist-info/METADATA,sha256=7Dpq2h0pfjQJWCk6ETX7I9Lqn3JthEJe-NVffOk5VL4,4769
+agent_guard_python-0.2.1.dist-info/WHEEL,sha256=7HL-TGvq44Ofp0yhZL-uRIIFHcJTIqqkRZVQ2wZidzM,96
+agent_guard_python-0.2.1.dist-info/sboms/agent-guard-python.cyclonedx.json,sha256=nhrbDSGl2L6nGrPCNS0RR_KJ7BB8II0HvZUWliD6Nqs,245381
+agent_guard_python-0.2.1.dist-info/RECORD,,

agent_guard_python-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp310-abi3-win_amd64