hydracuda 0.1.0__py3-none-any.whl

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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+hydracuda/__init__.py,sha256=J25xyJeQKGGI6VzEAjOcVlVgWTwmDZgXRIHRH1JGH0M,273
+hydracuda/cli.py,sha256=H660eMtePHeQUAWTqKUfySjXra8tq08Fevz5cPIC3dY,2103
+hydracuda/engine.py,sha256=8dPDoUS4R1_bJ39gRcONfwuJtdtZbgbPTynpO9khTEE,2228
+hydracuda/policy.py,sha256=lS_QELw_ixIu8OHPcw4a8-cR8H4j9_NnpCE7cZXAHQY,2565
+hydracuda/proxy.py,sha256=7GJZJwEyHMH5JJ6J0bgFLWaqobgsIWMAp85LOLBoYJ8,2002
+hydracuda-0.1.0.dist-info/METADATA,sha256=-0o7XjBMVEryehDrXsq-rFyF0N9RyMMeUb247A_KWeM,6867
+hydracuda-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+hydracuda-0.1.0.dist-info/entry_points.txt,sha256=noZB1zRElkb4Om2MqqpmgjV7IstJuoIMMRYgvWslzS0,49
+hydracuda-0.1.0.dist-info/licenses/LICENSE,sha256=1VWM1BnI1GvclYBky5f5Y9HqeThmQUwCWQbsFQM1Eu0,14
+hydracuda-0.1.0.dist-info/RECORD,,

hydracuda-0.1.0.dist-info/WHEEL

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

hydracuda-0.1.0.dist-info/entry_points.txt

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

hydracuda-0.1.0.dist-info/licenses/LICENSE

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