agentguardproxy 0.2.0__tar.gz

agentguardproxy-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: agentguardproxy
+Version: 0.2.0
+Summary: Python SDK for AgentGuard — the firewall for AI agents
+Author: AgentGuard Contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/Caua-ferraz/AgentGuard
+Project-URL: Repository, https://github.com/Caua-ferraz/AgentGuard
+Project-URL: Documentation, https://github.com/Caua-ferraz/AgentGuard/blob/master/docs/SETUP.md
+Project-URL: Issues, https://github.com/Caua-ferraz/AgentGuard/issues
+Keywords: ai,agents,firewall,policy,guardrails,safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.1.0; extra == "crewai"
+Provides-Extra: browser-use
+Requires-Dist: browser-use>=0.1.0; extra == "browser-use"
+Provides-Extra: mcp
+Provides-Extra: all
+Requires-Dist: langchain>=0.1.0; extra == "all"
+Requires-Dist: crewai>=0.1.0; extra == "all"
+Requires-Dist: browser-use>=0.1.0; extra == "all"
+
+# AgentGuard Python SDK
+
+Lightweight Python client for [AgentGuard](https://github.com/Caua-ferraz/AgentGuard) — the firewall for AI agents.
+
+## Install
+
+```bash
+pip install agentguard
+
+# With framework adapters
+pip install agentguard[langchain]
+pip install agentguard[crewai]
+pip install agentguard[browser-use]
+pip install agentguard[all]
+```
+
+## Quick Start
+
+```python
+from agentguard import Guard
+
+guard = Guard("http://localhost:8080", agent_id="my-agent")
+
+# Check before executing
+result = guard.check("shell", command="rm -rf ./old_data")
+
+if result.allowed:
+    execute(command)
+elif result.needs_approval:
+    print(f"Approve at: {result.approval_url}")
+else:
+    print(f"Blocked: {result.reason}")
+```
+
+## Framework Adapters
+
+### LangChain
+
+```python
+from agentguard.adapters.langchain import GuardedToolkit
+
+toolkit = GuardedToolkit(
+    tools=my_tools,
+    guard_url="http://localhost:8080",
+    agent_id="langchain-agent",
+)
+
+agent = create_react_agent(llm, toolkit.tools, prompt)
+```
+
+### CrewAI
+
+```python
+from agentguard.adapters.crewai import guard_crew_tools
+
+guarded_tools = guard_crew_tools(
+    tools=my_crew_tools,
+    guard_url="http://localhost:8080",
+    agent_id="crew-agent",
+)
+```
+
+### browser-use
+
+```python
+from agentguard.adapters.browseruse import GuardedBrowser
+
+browser = GuardedBrowser(guard_url="http://localhost:8080")
+
+result = browser.check_navigation("https://example.com")
+if result.allowed:
+    await page.goto("https://example.com")
+```
+
+### MCP
+
+```python
+from agentguard.adapters.mcp import GuardedMCPServer
+
+server = GuardedMCPServer(guard_url="http://localhost:8080")
+server.add_tool("my_tool", "Description", handler=my_handler)
+server.run()  # Starts stdio MCP server
+```
+
+## API Reference
+
+### `Guard(base_url, agent_id="")`
+- `check(scope, *, action, command, path, domain, url, meta)` — Check an action against policy
+- `approve(approval_id)` — Approve a pending action
+- `deny(approval_id)` — Deny a pending action
+- `wait_for_approval(approval_id, timeout=300)` — Block until resolved
+
+### `CheckResult`
+- `.allowed` — True if action is permitted
+- `.denied` — True if action is blocked
+- `.needs_approval` — True if human approval required
+- `.decision` — Raw decision string
+- `.reason` — Explanation
+- `.approval_url` — URL to approve (when applicable)
+
+### `@guarded(scope, guard=None)` decorator
+Wraps a function so it's checked before execution.
+
+## License
+
+Apache 2.0

agentguardproxy-0.2.0/README.md

@@ -0,0 +1,106 @@
+# AgentGuard Python SDK
+
+Lightweight Python client for [AgentGuard](https://github.com/Caua-ferraz/AgentGuard) — the firewall for AI agents.
+
+## Install
+
+```bash
+pip install agentguard
+
+# With framework adapters
+pip install agentguard[langchain]
+pip install agentguard[crewai]
+pip install agentguard[browser-use]
+pip install agentguard[all]
+```
+
+## Quick Start
+
+```python
+from agentguard import Guard
+
+guard = Guard("http://localhost:8080", agent_id="my-agent")
+
+# Check before executing
+result = guard.check("shell", command="rm -rf ./old_data")
+
+if result.allowed:
+    execute(command)
+elif result.needs_approval:
+    print(f"Approve at: {result.approval_url}")
+else:
+    print(f"Blocked: {result.reason}")
+```
+
+## Framework Adapters
+
+### LangChain
+
+```python
+from agentguard.adapters.langchain import GuardedToolkit
+
+toolkit = GuardedToolkit(
+    tools=my_tools,
+    guard_url="http://localhost:8080",
+    agent_id="langchain-agent",
+)
+
+agent = create_react_agent(llm, toolkit.tools, prompt)
+```
+
+### CrewAI
+
+```python
+from agentguard.adapters.crewai import guard_crew_tools
+
+guarded_tools = guard_crew_tools(
+    tools=my_crew_tools,
+    guard_url="http://localhost:8080",
+    agent_id="crew-agent",
+)
+```
+
+### browser-use
+
+```python
+from agentguard.adapters.browseruse import GuardedBrowser
+
+browser = GuardedBrowser(guard_url="http://localhost:8080")
+
+result = browser.check_navigation("https://example.com")
+if result.allowed:
+    await page.goto("https://example.com")
+```
+
+### MCP
+
+```python
+from agentguard.adapters.mcp import GuardedMCPServer
+
+server = GuardedMCPServer(guard_url="http://localhost:8080")
+server.add_tool("my_tool", "Description", handler=my_handler)
+server.run()  # Starts stdio MCP server
+```
+
+## API Reference
+
+### `Guard(base_url, agent_id="")`
+- `check(scope, *, action, command, path, domain, url, meta)` — Check an action against policy
+- `approve(approval_id)` — Approve a pending action
+- `deny(approval_id)` — Deny a pending action
+- `wait_for_approval(approval_id, timeout=300)` — Block until resolved
+
+### `CheckResult`
+- `.allowed` — True if action is permitted
+- `.denied` — True if action is blocked
+- `.needs_approval` — True if human approval required
+- `.decision` — Raw decision string
+- `.reason` — Explanation
+- `.approval_url` — URL to approve (when applicable)
+
+### `@guarded(scope, guard=None)` decorator
+Wraps a function so it's checked before execution.
+
+## License
+
+Apache 2.0

agentguardproxy-0.2.0/agentguard/__init__.py

@@ -0,0 +1,197 @@
+"""
+AgentGuard Python SDK
+
+Lightweight client for checking actions against AgentGuard policies.
+
+Usage:
+    from agentguard import Guard
+
+    guard = Guard("http://localhost:8080")
+    result = guard.check("shell", command="rm -rf ./data")
+
+    if result.allowed:
+        execute(command)
+    elif result.needs_approval:
+        print(f"Approve at: {result.approval_url}")
+    else:
+        print(f"Blocked: {result.reason}")
+"""
+
+import json
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+from urllib import request, error
+
+
+@dataclass
+class CheckResult:
+    """Result of a policy check."""
+    decision: str
+    reason: str
+    matched_rule: str = ""
+    approval_id: str = ""
+    approval_url: str = ""
+
+    @property
+    def allowed(self) -> bool:
+        return self.decision == "ALLOW"
+
+    @property
+    def denied(self) -> bool:
+        return self.decision == "DENY"
+
+    @property
+    def needs_approval(self) -> bool:
+        return self.decision == "REQUIRE_APPROVAL"
+
+
+class Guard:
+    """Client for the AgentGuard proxy."""
+
+    def __init__(self, base_url: str = "http://localhost:8080", agent_id: str = ""):
+        self.base_url = base_url.rstrip("/")
+        self.agent_id = agent_id
+
+    def check(
+        self,
+        scope: str,
+        *,
+        action: str = "",
+        command: str = "",
+        path: str = "",
+        domain: str = "",
+        url: str = "",
+        meta: Optional[dict] = None,
+    ) -> CheckResult:
+        """Check an action against the policy.
+
+        Args:
+            scope: The rule scope (filesystem, shell, network, browser, cost, data)
+            action: Action type (read, write, delete) — used with filesystem scope
+            command: Shell command string — used with shell scope
+            path: File path — used with filesystem scope
+            domain: Target domain — used with network/browser scope
+            url: Full URL — used with network scope
+            meta: Additional metadata
+
+        Returns:
+            CheckResult with the policy decision
+        """
+        payload = {
+            "scope": scope,
+            "agent_id": self.agent_id,
+        }
+        if action:
+            payload["action"] = action
+        if command:
+            payload["command"] = command
+        if path:
+            payload["path"] = path
+        if domain:
+            payload["domain"] = domain
+        if url:
+            payload["url"] = url
+        if meta:
+            payload["meta"] = meta
+
+        data = json.dumps(payload).encode("utf-8")
+        req = request.Request(
+            f"{self.base_url}/v1/check",
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+
+        try:
+            with request.urlopen(req, timeout=5) as resp:
+                body = json.loads(resp.read())
+                return CheckResult(
+                    decision=body.get("decision", "DENY"),
+                    reason=body.get("reason", ""),
+                    matched_rule=body.get("matched_rule", ""),
+                    approval_id=body.get("approval_id", ""),
+                    approval_url=body.get("approval_url", ""),
+                )
+        except error.URLError as e:
+            # If AgentGuard is unreachable, default to deny (fail closed)
+            return CheckResult(
+                decision="DENY",
+                reason=f"AgentGuard unreachable: {e}",
+            )
+
+    def approve(self, approval_id: str) -> bool:
+        """Approve a pending action."""
+        req = request.Request(
+            f"{self.base_url}/v1/approve/{approval_id}",
+            method="POST",
+        )
+        try:
+            with request.urlopen(req, timeout=5):
+                return True
+        except error.URLError:
+            return False
+
+    def deny(self, approval_id: str) -> bool:
+        """Deny a pending action."""
+        req = request.Request(
+            f"{self.base_url}/v1/deny/{approval_id}",
+            method="POST",
+        )
+        try:
+            with request.urlopen(req, timeout=5):
+                return True
+        except error.URLError:
+            return False
+
+    def wait_for_approval(self, approval_id: str, timeout: int = 300, poll_interval: int = 2) -> CheckResult:
+        """Block until a pending action is approved or denied (or timeout)."""
+        deadline = time.time() + timeout
+        while time.time() < deadline:
+            # Poll the status endpoint for resolution
+            req = request.Request(
+                f"{self.base_url}/v1/status/{approval_id}",
+                method="GET",
+            )
+            try:
+                with request.urlopen(req, timeout=5) as resp:
+                    body = json.loads(resp.read())
+                    if body.get("status") == "resolved" and body.get("decision") in ("ALLOW", "DENY"):
+                        return CheckResult(
+                            decision=body["decision"],
+                            reason=body.get("reason", "resolved"),
+                        )
+            except error.URLError:
+                pass
+            time.sleep(poll_interval)
+
+        return CheckResult(decision="DENY", reason="Approval timed out")
+
+
+# Convenience decorator for guarding functions
+def guarded(scope: str, guard: Optional[Guard] = None, **check_kwargs):
+    """Decorator that checks policy before executing a function.
+
+    Usage:
+        guard = Guard("http://localhost:8080")
+
+        @guarded("shell", guard=guard)
+        def run_command(cmd: str):
+            os.system(cmd)
+    """
+    def decorator(func):
+        def wrapper(*args, **kwargs):
+            g = guard or Guard()
+            # Try to extract meaningful info from args
+            cmd = args[0] if args else kwargs.get("command", kwargs.get("cmd", ""))
+            result = g.check(scope, command=str(cmd), **check_kwargs)
+            if result.allowed:
+                return func(*args, **kwargs)
+            elif result.needs_approval:
+                raise PermissionError(
+                    f"Action requires approval. Approve at: {result.approval_url}"
+                )
+            else:
+                raise PermissionError(f"Action denied by AgentGuard: {result.reason}")
+        return wrapper
+    return decorator

agentguardproxy-0.2.0/agentguard/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""AgentGuard framework adapters.
+
+Available adapters:
+    - langchain: Wraps LangChain tools with policy enforcement
+    - crewai: Wraps CrewAI tools with policy enforcement
+    - browseruse: Wraps browser-use actions with policy enforcement
+    - mcp: MCP-compatible server that enforces policies on tool calls
+"""

agentguardproxy-0.2.0/agentguard/adapters/browseruse.py

@@ -0,0 +1,128 @@
+"""
+AgentGuard browser-use Adapter
+
+Wraps browser-use actions so navigation, clicks, and form inputs pass through
+AgentGuard policy checks before execution.
+
+Usage:
+    from agentguard.adapters.browseruse import GuardedBrowser
+
+    browser = GuardedBrowser(
+        guard_url="http://localhost:8080",
+        agent_id="my-browser-agent",
+    )
+
+    # Check before navigating
+    result = browser.check_navigation("https://example.com")
+    if result.allowed:
+        await page.goto("https://example.com")
+"""
+
+from typing import Any, Optional
+from urllib.parse import urlparse
+from agentguard import Guard, CheckResult
+
+
+class GuardedBrowser:
+    """Policy-enforced wrapper for browser-use automation.
+
+    browser-use exposes a Browser/BrowserContext that agents drive. This class
+    provides guard methods that should be called before performing browser actions.
+    It can also wrap a browser-use Browser instance to intercept calls automatically.
+    """
+
+    def __init__(
+        self,
+        guard: Optional[Guard] = None,
+        guard_url: str = "http://localhost:8080",
+        agent_id: str = "",
+        browser: Any = None,
+    ):
+        self._guard = guard or Guard(guard_url, agent_id=agent_id)
+        self._browser = browser
+
+    def check_navigation(self, url: str) -> CheckResult:
+        """Check if navigation to a URL is allowed by policy."""
+        domain = ""
+        try:
+            parsed = urlparse(url)
+            domain = parsed.hostname or ""
+        except Exception:
+            pass
+
+        return self._guard.check("browser", url=url, domain=domain)
+
+    def check_action(self, action: str, target: str = "", meta: Optional[dict] = None) -> CheckResult:
+        """Check a browser action (click, type, etc.) against policy.
+
+        Args:
+            action: The action type (e.g., "click", "type", "screenshot")
+            target: The target selector or URL
+            meta: Additional context
+        """
+        return self._guard.check(
+            "browser",
+            command=f"{action} {target}".strip(),
+            meta=meta,
+        )
+
+    def check_form_input(self, url: str, field_name: str, value: str) -> CheckResult:
+        """Check if typing into a form field is allowed.
+
+        This is useful for preventing PII or credential leakage into web forms.
+        """
+        domain = ""
+        try:
+            parsed = urlparse(url)
+            domain = parsed.hostname or ""
+        except Exception:
+            pass
+
+        return self._guard.check(
+            "data",
+            domain=domain,
+            command=f"input:{field_name}",
+            meta={"field": field_name, "url": url},
+        )
+
+    def wrap_page(self, page: Any) -> "GuardedPage":
+        """Wrap a browser-use Page object with policy enforcement.
+
+        Returns a GuardedPage that intercepts goto() and other navigation methods.
+        """
+        return GuardedPage(page, self._guard)
+
+
+class GuardedPage:
+    """Wraps a browser-use Page to enforce policies on navigation."""
+
+    def __init__(self, page: Any, guard: Guard):
+        self._page = page
+        self._guard = guard
+
+    async def goto(self, url: str, **kwargs) -> Any:
+        """Navigate to a URL after policy check."""
+        domain = ""
+        try:
+            parsed = urlparse(url)
+            domain = parsed.hostname or ""
+        except Exception:
+            pass
+
+        result = self._guard.check("browser", url=url, domain=domain)
+
+        if result.allowed:
+            return await self._page.goto(url, **kwargs)
+        elif result.needs_approval:
+            raise PermissionError(
+                f"[AgentGuard] Navigation requires approval. "
+                f"Approve at: {result.approval_url}"
+            )
+        else:
+            raise PermissionError(
+                f"[AgentGuard] Navigation denied: {result.reason}"
+            )
+
+    def __getattr__(self, name: str) -> Any:
+        """Proxy all other attributes to the wrapped page."""
+        return getattr(self._page, name)