hydracuda 0.1.0__tar.gz

hydracuda-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish HYDRACUDA to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build
+
+      - run: python -m build
+
+      - uses: pypa/gh-action-pypi-publish@v1.12.3

hydracuda-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.pyc
+.env
+.venv
+.envrc
+.pytest_cache/
+.mypy_cache/
+.dist/
+build/
+dist/
+*.egg-info/
+tests/test_live.py
+baracuda.yaml
+hydracuda.yaml
+.baracuda/
+.hydracuda/

hydracuda-0.1.0/LICENSE

@@ -0,0 +1 @@
+404: Not Found

hydracuda-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: hydracuda
+Version: 0.1.0
+Summary: Hybrid Runtime Access Control for Untrusted Delegated Actions. Runtime policy enforcement proxy for AI tool calls.
+Project-URL: Homepage, https://github.com/Xtrinel-Group/HYDRACUDA
+Project-URL: Issues, https://github.com/Xtrinel-Group/HYDRACUDA/issues
+License: 404: Not Found
+License-File: LICENSE
+Keywords: ai,guardrails,llm,mcp,policy,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.19
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://assets.xtrinel.com/hydracuda-full.svg" alt="HYDRACUDA" width="480" />
+</p>
+
+# HYDRACUDA
+
+Hybrid Runtime Access Control for Untrusted Delegated Actions.
+
+HYDRACUDA is a lightweight, open source policy enforcement layer for AI tool calls.  
+Define a YAML policy file, drop HYDRACUDA in front of any MCP server or LLM tool layer, and every call is either allowed, denied, or held for review before it executes.
+
+The goal is simple: prevent tool-call abuse and out-of-scope actions while keeping everything local, auditable, and easy to reason about.
+
+---
+
+## Features
+
+- **Language-agnostic policy file**  
+  Human-readable `hydracuda.yaml` drives all decisions. Version-controlled, reviewable, and independent of any specific model or framework.
+
+- **Pre-dispatch enforcement**  
+  Tool calls are intercepted before they execute, not after. The model cannot bypass the decision by reprompting.
+
+- **Three decisions: allow, deny, review**  
+  - `allow` forwards the call to your handler  
+  - `deny` blocks the call with a clear reason  
+  - `review` is reserved for high-risk actions that will require human approval in a later version
+
+- **Local audit logging**  
+  Every decision is written to a SQLite audit log on disk. No telemetry, no external service, no cloud dependency.
+
+- **Two primary use cases**
+  - **Production guardrail** for AI-integrated applications
+  - **Engagement scope enforcement** for red teams using AI assistants during assessments
+
+---
+
+## Installation
+
+HYDRACUDA targets Python 3.10 and above.
+
+```bash
+pip install hydracuda
+```
+
+To work on the project locally:
+
+```bash
+git clone https://github.com/Xtrinel-Group/HYDRACUDA.git
+cd HYDRACUDA
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+From a new or existing project directory:
+
+```bash
+hydracuda init
+```
+
+This writes a starter `hydracuda.yaml` with commented examples.
+
+Validate the policy:
+
+```bash
+hydracuda check hydracuda.yaml
+```
+
+If validation passes, you can integrate HYDRACUDA into your tool-calling layer.
+
+### Minimal integration example
+
+```python
+import asyncio
+from hydracuda.policy import load_policy
+from hydracuda.engine import PolicyEngine
+from hydracuda.proxy import ToolCallProxy
+
+
+async def handle_tool_call(tool_name: str, params: dict) -> dict:
+    # Your existing tool dispatch logic goes here.
+    # For example, calling into an MCP server or a local command.
+    return {"status": "ok", "tool": tool_name, "params": params}
+
+
+async def main() -> None:
+    policy = load_policy("hydracuda.yaml")
+    engine = PolicyEngine(policy)
+    proxy = ToolCallProxy(engine, audit_path=policy.audit_path)
+
+    # This is what your LLM agent would have requested.
+    tool_name = "read_file"
+    params = {"path": "/tmp/example.txt"}
+
+    result = await proxy.call(tool_name, params, handler=handle_tool_call)
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+In your real application, the LLM agent calls `proxy.call(...)` instead of invoking tools directly.
+
+---
+
+## Policy File
+
+HYDRACUDA policies are defined in YAML. The file created by `hydracuda init` looks similar to this:
+
+```yaml
+version: 1
+mode: enforce   # enforce | shadow | review
+
+tools:
+  read_file:
+    allow: true
+    parameterRules:
+      path:
+        denyPatterns:
+          - "\\.\\."          # block path traversal
+          - "/etc/"
+          - "/root/"
+
+  delete_record:
+    allow: false
+    reason: "Destructive operation. Blocked by default."
+
+  execute_shell:
+    allow: review
+    rateLimit: "3/minute"
+
+audit:
+  path: .hydracuda/audit.db
+```
+
+Key concepts:
+
+- **mode**
+  - `enforce`: violations are blocked
+  - `shadow`: violations are logged but not blocked
+  - `review`: intended for future human-approval workflows
+
+- **tools**  
+  Each tool has an `allow` value:
+  - `true`  → allowed (subject to parameter rules)
+  - `false` → always denied
+  - `"review"` → queued for human review in a future release
+
+- **parameterRules**  
+  `denyPatterns` are Python regular expressions evaluated against the string value of the parameter.
+
+- **audit.path**  
+  Path to the SQLite audit database. The parent directory is created automatically if it does not exist.
+
+---
+
+## Audit Log
+
+HYDRACUDA writes one row per tool call decision to a local SQLite database.
+
+Table schema:
+
+- `id` (integer primary key)
+- `timestamp` (ISO 8601 string)
+- `tool` (tool name)
+- `action` (`allow`, `deny`, `review`)
+- `reason` (short explanation)
+- `params` (JSON-encoded parameters)
+
+This makes it easy to:
+
+- Review which tools are actually used in production
+- See which policies are firing most often
+- Build dashboards or alerts on top of the audit data
+
+---
+
+## Relationship to VAAST
+
+HYDRACUDA is maintained by Xtrinel, the team behind **VAAST**, an AI security scanner focused on AI attack surfaces and MCP tool-call abuse.
+
+- VAAST is **offensive**: it discovers tool-call abuse and prompt injection vulnerabilities in AI-integrated applications before they reach production.
+- HYDRACUDA is **defensive**: it enforces the policies that prevent those same vulnerabilities from being exploited at runtime.
+
+They are fully decoupled. HYDRACUDA does not require VAAST, but future versions will support importing VAAST findings to auto-generate policy templates.
+
+---
+
+## Documentation
+
+For full documentation, examples, and integration guides:
+
+- https://docs.xtrinel.com/hydracuda
+
+---
+
+## Logo and Branding
+
+HYDRACUDA assets are available under the Xtrinel brand guidelines:
+
+- Full wordmark: `https://assets.xtrinel.com/hydracuda-full.svg`
+- Icon: `https://assets.xtrinel.com/hydracuda.svg`
+
+You can use these in dashboards, internal docs, or integrations that surface HYDRACUDA decisions.
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for any new behavior
+4. Run `pytest`
+5. Open a pull request with a clear description of the change
+
+Please keep new features focused and security-oriented. If you are proposing a change to the policy format, open an issue first for discussion.
+
+---
+
+## License
+
+HYDRACUDA is released under the MIT License. See `LICENSE` for details.

hydracuda-0.1.0/README.md

@@ -0,0 +1,228 @@
+<p align="center">
+  <img src="https://assets.xtrinel.com/hydracuda-full.svg" alt="HYDRACUDA" width="480" />
+</p>
+
+# HYDRACUDA
+
+Hybrid Runtime Access Control for Untrusted Delegated Actions.
+
+HYDRACUDA is a lightweight, open source policy enforcement layer for AI tool calls.  
+Define a YAML policy file, drop HYDRACUDA in front of any MCP server or LLM tool layer, and every call is either allowed, denied, or held for review before it executes.
+
+The goal is simple: prevent tool-call abuse and out-of-scope actions while keeping everything local, auditable, and easy to reason about.
+
+---
+
+## Features
+
+- **Language-agnostic policy file**  
+  Human-readable `hydracuda.yaml` drives all decisions. Version-controlled, reviewable, and independent of any specific model or framework.
+
+- **Pre-dispatch enforcement**  
+  Tool calls are intercepted before they execute, not after. The model cannot bypass the decision by reprompting.
+
+- **Three decisions: allow, deny, review**  
+  - `allow` forwards the call to your handler  
+  - `deny` blocks the call with a clear reason  
+  - `review` is reserved for high-risk actions that will require human approval in a later version
+
+- **Local audit logging**  
+  Every decision is written to a SQLite audit log on disk. No telemetry, no external service, no cloud dependency.
+
+- **Two primary use cases**
+  - **Production guardrail** for AI-integrated applications
+  - **Engagement scope enforcement** for red teams using AI assistants during assessments
+
+---
+
+## Installation
+
+HYDRACUDA targets Python 3.10 and above.
+
+```bash
+pip install hydracuda
+```
+
+To work on the project locally:
+
+```bash
+git clone https://github.com/Xtrinel-Group/HYDRACUDA.git
+cd HYDRACUDA
+pip install -e .
+```
+
+---
+
+## Quick Start
+
+From a new or existing project directory:
+
+```bash
+hydracuda init
+```
+
+This writes a starter `hydracuda.yaml` with commented examples.
+
+Validate the policy:
+
+```bash
+hydracuda check hydracuda.yaml
+```
+
+If validation passes, you can integrate HYDRACUDA into your tool-calling layer.
+
+### Minimal integration example
+
+```python
+import asyncio
+from hydracuda.policy import load_policy
+from hydracuda.engine import PolicyEngine
+from hydracuda.proxy import ToolCallProxy
+
+
+async def handle_tool_call(tool_name: str, params: dict) -> dict:
+    # Your existing tool dispatch logic goes here.
+    # For example, calling into an MCP server or a local command.
+    return {"status": "ok", "tool": tool_name, "params": params}
+
+
+async def main() -> None:
+    policy = load_policy("hydracuda.yaml")
+    engine = PolicyEngine(policy)
+    proxy = ToolCallProxy(engine, audit_path=policy.audit_path)
+
+    # This is what your LLM agent would have requested.
+    tool_name = "read_file"
+    params = {"path": "/tmp/example.txt"}
+
+    result = await proxy.call(tool_name, params, handler=handle_tool_call)
+    print(result)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+In your real application, the LLM agent calls `proxy.call(...)` instead of invoking tools directly.
+
+---
+
+## Policy File
+
+HYDRACUDA policies are defined in YAML. The file created by `hydracuda init` looks similar to this:
+
+```yaml
+version: 1
+mode: enforce   # enforce | shadow | review
+
+tools:
+  read_file:
+    allow: true
+    parameterRules:
+      path:
+        denyPatterns:
+          - "\\.\\."          # block path traversal
+          - "/etc/"
+          - "/root/"
+
+  delete_record:
+    allow: false
+    reason: "Destructive operation. Blocked by default."
+
+  execute_shell:
+    allow: review
+    rateLimit: "3/minute"
+
+audit:
+  path: .hydracuda/audit.db
+```
+
+Key concepts:
+
+- **mode**
+  - `enforce`: violations are blocked
+  - `shadow`: violations are logged but not blocked
+  - `review`: intended for future human-approval workflows
+
+- **tools**  
+  Each tool has an `allow` value:
+  - `true`  → allowed (subject to parameter rules)
+  - `false` → always denied
+  - `"review"` → queued for human review in a future release
+
+- **parameterRules**  
+  `denyPatterns` are Python regular expressions evaluated against the string value of the parameter.
+
+- **audit.path**  
+  Path to the SQLite audit database. The parent directory is created automatically if it does not exist.
+
+---
+
+## Audit Log
+
+HYDRACUDA writes one row per tool call decision to a local SQLite database.
+
+Table schema:
+
+- `id` (integer primary key)
+- `timestamp` (ISO 8601 string)
+- `tool` (tool name)
+- `action` (`allow`, `deny`, `review`)
+- `reason` (short explanation)
+- `params` (JSON-encoded parameters)
+
+This makes it easy to:
+
+- Review which tools are actually used in production
+- See which policies are firing most often
+- Build dashboards or alerts on top of the audit data
+
+---
+
+## Relationship to VAAST
+
+HYDRACUDA is maintained by Xtrinel, the team behind **VAAST**, an AI security scanner focused on AI attack surfaces and MCP tool-call abuse.
+
+- VAAST is **offensive**: it discovers tool-call abuse and prompt injection vulnerabilities in AI-integrated applications before they reach production.
+- HYDRACUDA is **defensive**: it enforces the policies that prevent those same vulnerabilities from being exploited at runtime.
+
+They are fully decoupled. HYDRACUDA does not require VAAST, but future versions will support importing VAAST findings to auto-generate policy templates.
+
+---
+
+## Documentation
+
+For full documentation, examples, and integration guides:
+
+- https://docs.xtrinel.com/hydracuda
+
+---
+
+## Logo and Branding
+
+HYDRACUDA assets are available under the Xtrinel brand guidelines:
+
+- Full wordmark: `https://assets.xtrinel.com/hydracuda-full.svg`
+- Icon: `https://assets.xtrinel.com/hydracuda.svg`
+
+You can use these in dashboards, internal docs, or integrations that surface HYDRACUDA decisions.
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for any new behavior
+4. Run `pytest`
+5. Open a pull request with a clear description of the change
+
+Please keep new features focused and security-oriented. If you are proposing a change to the policy format, open an issue first for discussion.
+
+---
+
+## License
+
+HYDRACUDA is released under the MIT License. See `LICENSE` for details.

hydracuda-0.1.0/deprecation/README.md

@@ -0,0 +1,10 @@
+# baracuda (deprecated)
+
+This package has been renamed to **hydracuda**.
+
+Please uninstall this package and install the new one:
+
+```
+pip uninstall baracuda
+pip install hydracuda
+```

hydracuda-0.1.0/deprecation/baracuda/__init__.py

@@ -0,0 +1,7 @@
+raise ImportError(
+    "\n\nThe 'baracuda' package has been renamed to 'hydracuda'.\n"
+    "Please update your environment:\n\n"
+    "    pip uninstall baracuda\n"
+    "    pip install hydracuda\n\n"
+    "GitHub: https://github.com/Xtrinel-Group/HYDRACUDA\n"
+)

hydracuda-0.1.0/deprecation/pyproject.toml

@@ -0,0 +1,16 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "baracuda"
+version = "0.2.0"
+description = "Deprecated. This package has been renamed to hydracuda. Run: pip install hydracuda"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://xtrinel.com/hydracuda"
+Repository = "https://github.com/Xtrinel-Group/HYDRACUDA"

hydracuda-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hydracuda"
+version = "0.1.0"
+description = "Hybrid Runtime Access Control for Untrusted Delegated Actions. Runtime policy enforcement proxy for AI tool calls."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+keywords = ["ai", "security", "mcp", "llm", "guardrails", "policy"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Development Status :: 3 - Alpha",
+]
+dependencies = [
+    "pyyaml>=6.0",
+    "aiosqlite>=0.19",
+]
+
+[project.urls]
+Homepage = "https://github.com/Xtrinel-Group/HYDRACUDA"
+Issues = "https://github.com/Xtrinel-Group/HYDRACUDA/issues"
+
+[project.scripts]
+hydracuda = "hydracuda.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hydracuda"]

hydracuda-0.1.0/src/hydracuda/__init__.py

@@ -0,0 +1,9 @@
+"""HYDRACUDA - Runtime policy enforcement for AI tool calls."""
+
+__version__ = "0.1.0"
+
+from hydracuda.engine import PolicyEngine
+from hydracuda.policy import load_policy
+from hydracuda.proxy import ToolCallProxy
+
+__all__ = ["PolicyEngine", "load_policy", "ToolCallProxy"]

hydracuda-0.1.0/src/hydracuda/cli.py

@@ -0,0 +1,87 @@
+"""CLI interface for HYDRACUDA."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from hydracuda.policy import load_policy
+
+STARTER_POLICY = """\
+version: 1
+mode: enforce
+audit_path: .hydracuda/audit.db
+
+tools:
+  read_file:
+    allow: true
+    parameter_rules:
+      path:
+        deny_patterns:
+          - "/etc/"
+          - "\\\\.\\\\."
+          - "/root/"
+
+  delete_record:
+    allow: false
+    reason: "Destructive operation. Blocked by default."
+
+  execute_shell:
+    allow: "review"
+    rate_limit: "3/minute"
+
+audit:
+  path: .hydracuda/audit.db
+"""
+
+
+def cmd_init(args: argparse.Namespace) -> None:
+    """Write a starter hydracuda.yaml to the current directory."""
+    target = Path("hydracuda.yaml")
+    if target.exists():
+        print(f"{target} already exists. Not overwriting.")
+        return
+
+    target.write_text(STARTER_POLICY)
+    print(f"Created {target} with starter policy. Edit it to match your tools.")
+
+
+def cmd_check(args: argparse.Namespace) -> None:
+    """Validate a policy file and print a summary."""
+    try:
+        policy = load_policy(args.policy_file)
+    except ValueError as e:
+        print(f"Validation failed: {e}")
+        sys.exit(1)
+
+    tool_count = len(policy.tools)
+    print(f"Policy valid. Mode: {policy.mode}, Tools configured: {tool_count}")
+
+
+def main() -> None:
+    """Entry point for the hydracuda CLI."""
+    parser = argparse.ArgumentParser(
+        prog="hydracuda",
+        description="HYDRACUDA - Runtime policy enforcement for AI tool calls.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("init", help="Create a starter hydracuda.yaml in the current directory")
+
+    check_parser = subparsers.add_parser("check", help="Validate a policy file")
+    check_parser.add_argument("policy_file", help="Path to the policy YAML file")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_usage()
+        sys.exit(0)
+
+    commands = {
+        "init": cmd_init,
+        "check": cmd_check,
+    }
+    commands[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

hydracuda-0.1.0/src/hydracuda/engine.py

@@ -0,0 +1,73 @@
+"""Policy evaluation core for HYDRACUDA."""
+
+import re
+from dataclasses import dataclass
+
+from hydracuda.policy import Policy
+
+
+@dataclass
+class Decision:
+    """Result of evaluating a tool call against a policy."""
+
+    action: str
+    reason: str
+    tool: str
+    params: dict
+
+
+class PolicyEngine:
+    """Evaluates tool calls against a loaded policy."""
+
+    def __init__(self, policy: Policy):
+        self.policy = policy
+
+    def evaluate(self, tool_name: str, params: dict) -> Decision:
+        """Evaluate a tool call and return an allow/deny/review decision."""
+        if tool_name not in self.policy.tools:
+            return Decision(
+                action="deny",
+                reason=f"{tool_name}: not listed in policy — default deny",
+                tool=tool_name,
+                params=params,
+            )
+
+        tool_policy = self.policy.tools[tool_name]
+
+        if tool_policy.allow is False:
+            return Decision(
+                action="deny",
+                reason="tool blocked by policy",
+                tool=tool_name,
+                params=params,
+            )
+
+        if tool_policy.allow == "review":
+            return Decision(
+                action="review",
+                reason="tool requires human review",
+                tool=tool_name,
+                params=params,
+            )
+
+        if tool_policy.parameter_rules:
+            for param_name, rules in tool_policy.parameter_rules.items():
+                if param_name not in params:
+                    continue
+                deny_patterns = rules.get("deny_patterns", [])
+                param_value = str(params[param_name])
+                for pattern in deny_patterns:
+                    if re.search(pattern, param_value):
+                        return Decision(
+                            action="deny",
+                            reason=f"{tool_name}: parameter '{param_name}' matched deny pattern '{pattern}'",
+                            tool=tool_name,
+                            params=params,
+                        )
+
+        return Decision(
+            action="allow",
+            reason="all policy checks passed",
+            tool=tool_name,
+            params=params,
+        )

hydracuda-0.1.0/src/hydracuda/policy.py

@@ -0,0 +1,84 @@
+"""YAML policy parser and validator for HYDRACUDA."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Union
+
+import yaml
+
+
+@dataclass
+class ToolPolicy:
+    """Policy configuration for a single tool."""
+
+    allow: Union[bool, str] = True
+    rate_limit: str | None = None
+    parameter_rules: dict[str, dict] | None = None
+
+
+@dataclass
+class Policy:
+    """Top-level policy configuration parsed from hydracuda.yaml."""
+
+    version: int
+    tools: dict[str, ToolPolicy]
+    mode: str = "enforce"
+    audit_path: str = ".hydracuda/audit.db"
+
+
+VALID_MODES = {"enforce", "shadow", "review"}
+
+
+def load_policy(path: str) -> Policy:
+    """Load and validate a hydracuda.yaml policy file.
+
+    Raises ValueError with a descriptive message on invalid input.
+    """
+    policy_path = Path(path)
+    if not policy_path.exists():
+        raise ValueError(f"Policy file not found: {path}")
+
+    with open(policy_path) as f:
+        raw = yaml.safe_load(f)
+
+    if not isinstance(raw, dict):
+        raise ValueError(f"Policy file must be a YAML mapping, got {type(raw).__name__}")
+
+    if "version" not in raw:
+        raise ValueError("Policy file missing required key: 'version'")
+
+    version = raw["version"]
+    if not isinstance(version, int):
+        raise ValueError(f"'version' must be an integer, got {type(version).__name__}")
+
+    mode = raw.get("mode", "enforce")
+    if mode not in VALID_MODES:
+        raise ValueError(f"'mode' must be one of {sorted(VALID_MODES)}, got '{mode}'")
+
+    if "tools" not in raw:
+        raise ValueError("Policy file missing required key: 'tools'")
+
+    raw_tools = raw["tools"]
+    if not isinstance(raw_tools, dict):
+        raise ValueError("'tools' must be a mapping of tool names to configurations")
+
+    tools: dict[str, ToolPolicy] = {}
+    for tool_name, tool_conf in raw_tools.items():
+        if not isinstance(tool_conf, dict):
+            raise ValueError(f"Tool '{tool_name}' configuration must be a mapping")
+
+        allow = tool_conf.get("allow", True)
+        if allow not in (True, False, "review"):
+            raise ValueError(
+                f"Tool '{tool_name}': 'allow' must be true, false, or 'review', got '{allow}'"
+            )
+
+        tools[tool_name] = ToolPolicy(
+            allow=allow,
+            rate_limit=tool_conf.get("rate_limit"),
+            parameter_rules=tool_conf.get("parameter_rules"),
+        )
+
+    audit_path = raw.get("audit_path", ".hydracuda/audit.db")
+
+    return Policy(version=version, mode=mode, tools=tools, audit_path=audit_path)

hydracuda-0.1.0/src/hydracuda/proxy.py

@@ -0,0 +1,58 @@
+"""Tool call interception layer for HYDRACUDA."""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import aiosqlite
+
+from hydracuda.engine import PolicyEngine
+
+
+class ToolCallProxy:
+    """Intercepts tool calls, enforces policy, and writes an audit log."""
+
+    def __init__(self, engine: PolicyEngine, audit_path: str | None = None):
+        self.engine = engine
+        self.audit_path = audit_path or engine.policy.audit_path
+
+    async def call(self, tool_name: str, params: dict, handler) -> dict:
+        """Evaluate, log, and optionally execute a tool call."""
+        decision = self.engine.evaluate(tool_name, params)
+        await self._write_audit(decision)
+
+        if decision.action == "deny":
+            raise PermissionError(decision.reason)
+
+        if decision.action == "review":
+            raise NotImplementedError(f"tool call queued for human review: {tool_name}")
+
+        return await handler(tool_name, params)
+
+    async def _write_audit(self, decision) -> None:
+        """Append a decision to the SQLite audit log."""
+        db_path = Path(self.audit_path)
+        db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        async with aiosqlite.connect(str(db_path)) as db:
+            await db.execute(
+                """CREATE TABLE IF NOT EXISTS audit_log (
+                    id INTEGER PRIMARY KEY,
+                    timestamp TEXT,
+                    tool TEXT,
+                    action TEXT,
+                    reason TEXT,
+                    params TEXT
+                )"""
+            )
+            await db.execute(
+                "INSERT INTO audit_log (timestamp, tool, action, reason, params) VALUES (?, ?, ?, ?, ?)",
+                (
+                    datetime.now(timezone.utc).isoformat(),
+                    decision.tool,
+                    decision.action,
+                    decision.reason,
+                    json.dumps(decision.params),
+                ),
+            )
+            await db.commit()

hydracuda-0.1.0/tests/test_engine.py

@@ -0,0 +1,90 @@
+"""Unit tests for the HYDRACUDA policy engine."""
+
+import pytest
+
+from hydracuda.engine import PolicyEngine
+from hydracuda.policy import Policy, ToolPolicy
+
+
+def make_policy(tools: dict[str, ToolPolicy]) -> Policy:
+    return Policy(version=1, tools=tools)
+
+
+def test_unconfigured_tool_defaults_to_deny():
+    engine = PolicyEngine(make_policy({}))
+    decision = engine.evaluate("unknown_tool", {"arg": "value"})
+
+    assert decision.action == "deny"
+    assert "not listed in policy" in decision.reason
+
+
+def test_tool_explicitly_denied():
+    engine = PolicyEngine(make_policy({
+        "dangerous_tool": ToolPolicy(allow=False),
+    }))
+    decision = engine.evaluate("dangerous_tool", {})
+
+    assert decision.action == "deny"
+    assert decision.reason == "tool blocked by policy"
+
+
+def test_tool_set_to_review():
+    engine = PolicyEngine(make_policy({
+        "sensitive_tool": ToolPolicy(allow="review"),
+    }))
+    decision = engine.evaluate("sensitive_tool", {"x": 1})
+
+    assert decision.action == "review"
+
+
+def test_deny_pattern_match():
+    engine = PolicyEngine(make_policy({
+        "read_file": ToolPolicy(
+            allow=True,
+            parameter_rules={
+                "path": {"deny_patterns": ["/etc/", "\\.\\."]}
+            },
+        ),
+    }))
+    decision = engine.evaluate("read_file", {"path": "/etc/passwd"})
+
+    assert decision.action == "deny"
+    assert "read_file" in decision.reason
+    assert "path" in decision.reason
+    assert "/etc/" in decision.reason
+
+
+def test_no_deny_pattern_match_returns_allow():
+    engine = PolicyEngine(make_policy({
+        "read_file": ToolPolicy(
+            allow=True,
+            parameter_rules={
+                "path": {"deny_patterns": ["/etc/", "\\.\\."]}
+            },
+        ),
+    }))
+    decision = engine.evaluate("read_file", {"path": "/home/user/notes.txt"})
+
+    assert decision.action == "allow"
+    assert decision.reason == "all policy checks passed"
+
+
+def test_unlisted_tool_denied_by_default():
+    engine = PolicyEngine(make_policy({
+        "read_file": ToolPolicy(allow=True),
+    }))
+    decision = engine.evaluate("send_email", {"to": "admin@corp.com"})
+
+    assert decision.action == "deny"
+    assert "send_email" in decision.reason
+    assert "default deny" in decision.reason
+
+
+def test_delete_record_blocked():
+    engine = PolicyEngine(make_policy({
+        "delete_record": ToolPolicy(allow=False),
+    }))
+    decision = engine.evaluate("delete_record", {"id": "usr_123"})
+
+    assert decision.action == "deny"
+    assert decision.reason == "tool blocked by policy"