mastyf-ai 4.2.0__tar.gz

mastyf_ai-4.2.0/.gitignore

@@ -0,0 +1,75 @@
+node_modules/
+build/
+.envrc
+*.tgz
+package.json.prepack-backup
+.packages.prepack-backup.json
+.venv-charts/
+dist/
+*.db
+.env
+.DS_Store
+*.log
+package-lock.json
+coverage/
+test-results/
+/reports/
+docs/tutorials/videos/.promo-build/
+docs/tutorials/videos/mastyf-ai-promo.mp4
+apps/cloud/public/tutorials/mastyf-ai-promo.mp4
+docs/tutorials/videos/*.mp4
+apps/cloud/public/tutorials/*.mp4
+.turbo/
+.threat-state.json
+.ai-learning.json
+default-policy-auto-generated.yaml
+scenarios/dogfood/output/
+scenarios/dogfood/sandbox/
+:memory:
+test-report.html
+test-report*.html
+corpus-eval-report.json
+/benchmark-report.json
+assets/ml/prompt-injection/onnx/*.onnx
+.venv/
+.package.prepack-backup.json
+scripts/.agent-proxy-config.json
+# Runtime auto-threat-research fixtures beyond committed corpus (adv-425+)
+/adversarial-harness/fixtures/custom-attacks/adv-42[5-9].json
+/adversarial-harness/fixtures/custom-attacks/adv-43[0-9].json
+/adversarial-harness/fixtures/custom-attacks/adv-[5-9][0-9][0-9].json
+# Accidental tsc output in package src trees
+packages/server/src/**/*.js
+packages/server/src/**/*.d.ts
+packages/server/src/**/*.js.map
+packages/server/src/**/*.d.ts.map
+scenarios/real-life/output/
+reports/tenants/
+reports/.mastyf-ai-home/
+*.db-shm
+*.db-wal
+*.db.pid
+reports/provenance-test.tar.gz
+reports/insurance-test/
+reports/home/tenants/default/dashboard-access.jsonl
+.vercel
+.env*.local
+*.tsbuildinfo
+apps/proxy-core/proxy-core
+benchmarks/results/
+sca/*.md
+sca/*.png
+sca/ai-learning-metrics.json
+deploy/dashboard.html
+deploy/dashboard-spa/out/
+deploy/dashboard-spa/.next/
+.next/
+# Generated at runtime by scenarios/tests — must never be committed (leaks local absolute paths)
+scenarios/real-life/proxy-filesystem-config.json
+tests/e2e/test-config.json
+tests/e2e/adversarial-test-config.json
+# Orphaned demo/report exports should live under gitignored reports/, never under app/data
+deploy/dashboard-spa/app/data/
+# Runtime logs
+data/tenants/default/logs/*.jsonl
+mastyf-ai-docker.tar

mastyf_ai-4.2.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: mastyf-ai
+Version: 4.2.0
+Summary: Mastyf AI — perimeter security proxy for MCP-based AI agents. Intercept, audit, and block dangerous tool calls.
+Project-URL: Homepage, https://mastyf.ai
+Project-URL: Repository, https://github.com/mastyf-ai/mastyf.ai
+Project-URL: Documentation, https://docs.mastyf.ai
+Author-email: Mastyf AI <dev@mastyf.ai>
+License: AGPL-3.0
+Keywords: ai,llm,mastyf,mcp,prompt-injection,proxy,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+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: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
+Provides-Extra: openai-agents
+Requires-Dist: openai>=1.0.0; extra == 'openai-agents'
+Description-Content-Type: text/markdown
+
+# Mastyf AI — Python SDK
+
+Perimeter security proxy for MCP-based AI agents. Evaluates every tool call through the Mastyf policy engine before execution.
+
+## Install
+
+```bash
+pip install mastyf-ai
+
+# With framework integrations:
+pip install mastyf-ai[openai-agents]  # OpenAI Agents SDK
+pip install mastyf-ai[langchain]      # LangChain
+```
+
+## Quick Start
+
+```python
+from mastyf_ai import MastyfProxy
+
+proxy = MastyfProxy("http://localhost:4000")
+
+# Check health
+print(proxy.health())  # {'status': 'ready'}
+
+# Test a tool call against policy
+decision = proxy.test_policy("read_file", {"path": "/etc/passwd"})
+print(f"{decision.action}: {decision.reason}")
+# Output: block: Path not in allowed list
+
+# Scan a package
+from mastyf_ai import TrustScanner
+scanner = TrustScanner()
+result = scanner.scan("@modelcontextprotocol/server-filesystem")
+print(f"{result['trustGrade']} ({result['trustScore']}/100)")
+```
+
+## Framework Integration
+
+### OpenAI Agents SDK
+
+```python
+from mastyf_ai import MastyfOpenAIGuard
+
+guard = MastyfOpenAIGuard("http://localhost:4000")
+
+@guard.wrap_tool
+async def read_file(path: str) -> str:
+    with open(path) as f:
+        return f.read()
+```
+
+### LangChain
+
+```python
+from mastyf_ai import MastyfLangChainGuard
+
+guard = MastyfLangChainGuard()
+safe_tool = guard.wrap_tool(my_langchain_tool)
+```
+
+## CLI
+
+```bash
+mastyf health
+mastyf test read_file --args '{"path":"/etc/passwd"}'
+mastyf scan @modelcontextprotocol/server-filesystem
+mastyf hooks
+mastyf audit
+```
+
+## API Reference
+
+See [docs.mastyf.ai](https://docs.mastyf.ai) for full API documentation.

mastyf_ai-4.2.0/README.md

@@ -0,0 +1,73 @@
+# Mastyf AI — Python SDK
+
+Perimeter security proxy for MCP-based AI agents. Evaluates every tool call through the Mastyf policy engine before execution.
+
+## Install
+
+```bash
+pip install mastyf-ai
+
+# With framework integrations:
+pip install mastyf-ai[openai-agents]  # OpenAI Agents SDK
+pip install mastyf-ai[langchain]      # LangChain
+```
+
+## Quick Start
+
+```python
+from mastyf_ai import MastyfProxy
+
+proxy = MastyfProxy("http://localhost:4000")
+
+# Check health
+print(proxy.health())  # {'status': 'ready'}
+
+# Test a tool call against policy
+decision = proxy.test_policy("read_file", {"path": "/etc/passwd"})
+print(f"{decision.action}: {decision.reason}")
+# Output: block: Path not in allowed list
+
+# Scan a package
+from mastyf_ai import TrustScanner
+scanner = TrustScanner()
+result = scanner.scan("@modelcontextprotocol/server-filesystem")
+print(f"{result['trustGrade']} ({result['trustScore']}/100)")
+```
+
+## Framework Integration
+
+### OpenAI Agents SDK
+
+```python
+from mastyf_ai import MastyfOpenAIGuard
+
+guard = MastyfOpenAIGuard("http://localhost:4000")
+
+@guard.wrap_tool
+async def read_file(path: str) -> str:
+    with open(path) as f:
+        return f.read()
+```
+
+### LangChain
+
+```python
+from mastyf_ai import MastyfLangChainGuard
+
+guard = MastyfLangChainGuard()
+safe_tool = guard.wrap_tool(my_langchain_tool)
+```
+
+## CLI
+
+```bash
+mastyf health
+mastyf test read_file --args '{"path":"/etc/passwd"}'
+mastyf scan @modelcontextprotocol/server-filesystem
+mastyf hooks
+mastyf audit
+```
+
+## API Reference
+
+See [docs.mastyf.ai](https://docs.mastyf.ai) for full API documentation.

mastyf_ai-4.2.0/mastyf_ai/__init__.py

@@ -0,0 +1,19 @@
+"""
+Mastyf AI — Python SDK for MCP security proxy.
+
+Usage:
+    from mastyf_ai import MastyfProxy
+
+    proxy = MastyfProxy("http://localhost:4000")
+    proxy.start()
+
+    # The proxy is now protecting all MCP tool calls
+"""
+
+from .client import MastyfProxy, MastyfConfig
+from .middleware.openai_agents import MastyfOpenAIGuard
+from .middleware.langchain import MastyfLangChainGuard
+from .scanner import TrustScanner
+
+__version__ = "4.2.0"
+__all__ = ["MastyfProxy", "MastyfConfig", "MastyfOpenAIGuard", "MastyfLangChainGuard", "TrustScanner"]

mastyf_ai-4.2.0/mastyf_ai/cli.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Mastyf AI CLI — Python entry point."""
+
+import argparse
+import json
+import sys
+from .client import MastyfProxy, MastyfConfig
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Mastyf AI — MCP security proxy client")
+    parser.add_argument("--proxy-url", default="http://localhost:4000", help="Proxy URL")
+    parser.add_argument("--api-key", help="API key for authentication")
+
+    sub = parser.add_subparsers(dest="command")
+
+    health = sub.add_parser("health", help="Check proxy health")
+    test = sub.add_parser("test", help="Test a tool call against policy")
+    test.add_argument("tool", help="Tool name")
+    test.add_argument("--args", default="{}", help="JSON arguments")
+    scan = sub.add_parser("scan", help="Scan an MCP package for trust score")
+    scan.add_argument("package", help="Package name")
+    hooks = sub.add_parser("hooks", help="List registered hooks")
+    audit = sub.add_parser("audit", help="Verify audit chain")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        return
+
+    proxy = MastyfProxy(MastyfConfig(proxy_url=args.proxy_url, api_key=args.api_key))
+
+    try:
+        if args.command == "health":
+            print(json.dumps(proxy.health(), indent=2))
+        elif args.command == "test":
+            tool_args = json.loads(args.args)
+            decision = proxy.test_policy(args.tool, tool_args)
+            print(f"Action: {decision.action}\nRule: {decision.rule}\nReason: {decision.reason}")
+        elif args.command == "scan":
+            from .scanner import TrustScanner
+            scanner = TrustScanner(args.proxy_url)
+            result = scanner.scan(args.package)
+            print(f"Package: {result.get('packageName')}")
+            print(f"Score: {result.get('trustScore')}/100")
+            print(f"Grade: {result.get('trustGrade')}")
+            print(f"Dimensions: {json.dumps(result.get('dimensions', {}), indent=2)}")
+        elif args.command == "hooks":
+            for h in proxy.get_hooks():
+                print(f"  {h['name']} ({h['type']}, enabled={h['enabled']})")
+        elif args.command == "audit":
+            chain = proxy.get_audit_chain()
+            print(f"Audit entries: {chain.get('entries', 0)}")
+            print(f"Integrity: {'OK' if chain.get('ok') else 'BROKEN (' + str(chain.get('breaks', 0)) + ' breaks)'}")
+    except Exception as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    finally:
+        proxy.close()

mastyf_ai-4.2.0/mastyf_ai/client.py

@@ -0,0 +1,130 @@
+"""Mastyf proxy client — connects to a running Mastyf AI proxy instance."""
+
+import httpx
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, List
+
+
+@dataclass
+class MastyfConfig:
+    proxy_url: str = "http://localhost:4000"
+    api_key: Optional[str] = None
+    tenant_id: str = "default"
+    timeout: float = 10.0
+
+
+@dataclass
+class PolicyDecision:
+    action: str  # "pass", "block", "flag"
+    rule: str
+    reason: str
+
+
+class MastyfProxy:
+    """Client for a running Mastyf AI proxy instance."""
+
+    def __init__(self, config: MastyfConfig | str = "http://localhost:4000"):
+        if isinstance(config, str):
+            config = MastyfConfig(proxy_url=config)
+        self.config = config
+        self._client = httpx.Client(
+            base_url=config.proxy_url.rstrip("/"),
+            timeout=config.timeout,
+            headers=self._build_headers(),
+        )
+
+    def _build_headers(self) -> Dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+        headers["X-Tenant-Id"] = self.config.tenant_id
+        return headers
+
+    def health(self) -> Dict[str, Any]:
+        """Check proxy health."""
+        r = self._client.get("/health")
+        r.raise_for_status()
+        return r.json()
+
+    def test_policy(self, tool: str, args: Dict[str, Any], server: str = "default") -> PolicyDecision:
+        """Test a tool call against the current policy without executing it."""
+        r = self._client.post("/api/policy/test", json={
+            "tool": tool,
+            "server": server,
+            "args": args,
+        })
+        r.raise_for_status()
+        data = r.json()
+        return PolicyDecision(
+            action=data.get("action", "pass"),
+            rule=data.get("rule", "unknown"),
+            reason=data.get("reason", ""),
+        )
+
+    def evaluate_tool_call(self, tool: str, args: Dict[str, Any], server: str = "default") -> PolicyDecision:
+        """Evaluate a tool call through the full policy engine and hooks."""
+        r = self._client.post(f"{self.config.proxy_url.rstrip('/')}/mcp", json={
+            "jsonrpc": "2.0",
+            "id": "python-sdk",
+            "method": "tools/call",
+            "params": {"name": tool, "arguments": args},
+        })
+        data = r.json()
+        if "error" in data:
+            err = data["error"]
+            return PolicyDecision(
+                action="block",
+                rule=err.get("data", {}).get("rule", "unknown"),
+                reason=err.get("message", ""),
+            )
+        return PolicyDecision(action="pass", rule="default", reason="")
+
+    def get_hooks(self) -> List[Dict[str, Any]]:
+        """List all registered hooks."""
+        r = self._client.get("/api/hooks")
+        r.raise_for_status()
+        return r.json().get("hooks", [])
+
+    def register_hook(self, name: str, code: str, hook_type: str = "before", priority: int = 50) -> bool:
+        """Register a custom hook."""
+        r = self._client.post("/api/hooks", json={
+            "name": name, "code": code, "type": hook_type, "priority": priority,
+        })
+        return r.status_code == 201
+
+    def store_credential(self, token: str, provider: str = "api", credential_type: str = "bearer_token") -> str:
+        """Store an API token in the encrypted credential broker."""
+        r = self._client.post("/api/credentials", json={
+            "token": token,
+            "providerName": provider,
+            "providerId": provider,
+            "credentialType": credential_type,
+        })
+        r.raise_for_status()
+        return r.json().get("id", "")
+
+    def get_audit_chain(self) -> Dict[str, Any]:
+        """Verify audit hash chain integrity."""
+        r = self._client.get("/api/audit/verify")
+        r.raise_for_status()
+        return r.json()
+
+    def get_learning_suggestions(self) -> List[Dict[str, Any]]:
+        """Get whitelist suggestions from learning mode."""
+        r = self._client.get("/api/learning/suggestions")
+        r.raise_for_status()
+        return r.json().get("suggestions", [])
+
+    def close(self):
+        self._client.close()
+
+
+def run_eval(proxy: MastyfProxy, payloads: List[Dict[str, Any]]) -> Dict[str, Any]:
+    """Run evaluation payloads against the proxy policy."""
+    r = httpx.post(
+        f"{proxy.config.proxy_url.rstrip('/')}/api/eval/run",
+        json={"payloads": payloads},
+        timeout=30.0,
+    )
+    r.raise_for_status()
+    return r.json()

mastyf_ai-4.2.0/mastyf_ai/middleware/__init__.py

@@ -0,0 +1 @@
+"""Mastyf AI middleware for Python agent frameworks."""

mastyf_ai-4.2.0/mastyf_ai/middleware/langchain.py

@@ -0,0 +1,45 @@
+"""LangChain integration for Mastyf AI security proxy."""
+
+from typing import Optional, Dict, Any, Callable
+from ..client import MastyfProxy
+
+
+class MastyfLangChainGuard:
+    """Middleware for LangChain that evaluates tool calls through Mastyf before execution."""
+
+    def __init__(self, proxy_url: str = "http://localhost:4000", api_key: Optional[str] = None):
+        self._proxy = MastyfProxy(proxy_url)
+
+    def wrap_tool(self, tool: Any) -> Any:
+        """Wrap a LangChain tool with Mastyf policy evaluation."""
+        tool_name = getattr(tool, "name", tool.__class__.__name__)
+        original_invoke = tool._run if hasattr(tool, "_run") else tool.invoke
+
+        def safe_invoke(*args: Any, **kwargs: Any) -> Any:
+            args_dict = kwargs or {}
+            if args and len(args) > 0 and isinstance(args[0], str):
+                args_dict = {"input": args[0]}
+            decision = self._proxy.test_policy(tool_name, args_dict)
+            if decision.action == "block":
+                raise PermissionError(f"Mastyf blocked '{tool_name}': {decision.reason}")
+            return original_invoke(*args, **kwargs)
+
+        if hasattr(tool, "_run"):
+            tool._run = safe_invoke
+        else:
+            tool.invoke = safe_invoke
+        return tool
+
+    def create_callback(self) -> Callable:
+        """Create a callback for LangChain agent runs."""
+        def on_tool_start(tool_name: str, input_str: str) -> None:
+            import json
+            try:
+                args = json.loads(input_str)
+            except Exception:
+                args = {"input": input_str}
+            decision = self._proxy.test_policy(tool_name, args)
+            if decision.action == "block":
+                raise PermissionError(f"Mastyf blocked '{tool_name}': {decision.reason}")
+
+        return on_tool_start

mastyf_ai-4.2.0/mastyf_ai/middleware/openai_agents.py

@@ -0,0 +1,33 @@
+"""OpenAI Agents SDK integration for Mastyf AI security proxy."""
+
+from typing import Optional, Dict, Any
+from ..client import MastyfProxy, PolicyDecision
+
+
+class MastyfOpenAIGuard:
+    """Guard middleware for OpenAI Agents SDK that evaluates all tool calls through Mastyf."""
+
+    def __init__(self, proxy_url: str = "http://localhost:4000", api_key: Optional[str] = None):
+        self._proxy = MastyfProxy(proxy_url) if isinstance(proxy_url, str) else proxy_url
+        self._proxy.config.api_key = api_key
+
+    async def before_tool_call(self, tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]:
+        """Called before every tool execution. Returns {'allowed': bool, 'reason': str}."""
+        decision = self._proxy.test_policy(tool_name, args)
+        return {
+            "allowed": decision.action != "block",
+            "reason": decision.reason if decision.action == "block" else "",
+        }
+
+    def wrap_tool(self, tool_fn, tool_name: str):
+        """Wrap a tool function with policy evaluation."""
+        original = tool_fn
+
+        async def wrapped(**kwargs):
+            decision = self._proxy.test_policy(tool_name, kwargs)
+            if decision.action == "block":
+                raise PermissionError(f"Mastyf blocked '{tool_name}': {decision.reason}")
+            return await original(**kwargs)
+
+        wrapped.__name__ = tool_name
+        return wrapped

mastyf_ai-4.2.0/mastyf_ai/scanner.py

@@ -0,0 +1,33 @@
+"""MCP package trust scanner — scan npm packages for security grades."""
+
+from typing import Dict, Any, Optional
+from ..client import MastyfProxy
+
+
+class TrustScanner:
+    """Scan MCP server packages for trust scores."""
+
+    def __init__(self, proxy_url: str = "http://localhost:4000"):
+        self._proxy = MastyfProxy(proxy_url)
+
+    def scan(self, package_name: str) -> Dict[str, Any]:
+        """Scan a package and return its trust score."""
+        import httpx
+        r = httpx.post(
+            f"{self._proxy.config.proxy_url.rstrip('/')}/api/registry/scan",
+            json={"packageName": package_name},
+            timeout=15.0,
+        )
+        r.raise_for_status()
+        data = r.json()
+        return data.get("result", {})
+
+    def score(self, package_name: str) -> Optional[int]:
+        """Return just the numeric trust score (0-100)."""
+        result = self.scan(package_name)
+        return result.get("trustScore")
+
+    def grade(self, package_name: str) -> Optional[str]:
+        """Return just the trust grade (A+ through F)."""
+        result = self.scan(package_name)
+        return result.get("trustGrade")

mastyf_ai-4.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mastyf-ai"
+version = "4.2.0"
+description = "Mastyf AI — perimeter security proxy for MCP-based AI agents. Intercept, audit, and block dangerous tool calls."
+readme = "README.md"
+license = {text = "AGPL-3.0"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Mastyf AI", email = "dev@mastyf.ai"},
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "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",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+]
+keywords = ["mcp", "security", "ai", "llm", "proxy", "prompt-injection", "mastyf"]
+
+[project.optional-dependencies]
+openai-agents = ["openai>=1.0.0"]
+langchain = ["langchain-core>=0.3.0"]
+
+[project.urls]
+Homepage = "https://mastyf.ai"
+Repository = "https://github.com/mastyf-ai/mastyf.ai"
+Documentation = "https://docs.mastyf.ai"
+
+[project.scripts]
+mastyf = "mastyf_ai.cli:main"