mcpshield-runtime 0.1.0__py3-none-any.whl

mcpshield_runtime-0.1.0.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: mcpshield-runtime
+Version: 0.1.0
+Summary: Secure MCP runtime — policy enforcement, SSRF blocking, audit logging
+Author: Sri Sowmya Nemani
+License: MIT
+Project-URL: Homepage, https://github.com/srisowmya2000/mcp-shield
+Project-URL: Repository, https://github.com/srisowmya2000/mcp-shield
+Keywords: mcp,security,ssrf,llm,agent,policy,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Security
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: typer>=0.12
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+
+# mcp-shield 🛡️
+
+> **The security runtime for MCP servers.**  
+> Every tool call inspected. Every attack blocked. Every decision logged.
+
+![Python](https://img.shields.io/badge/python-3.12-blue?style=flat-square)
+![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)
+![Tests](https://img.shields.io/badge/tests-12%20passing-brightgreen?style=flat-square)
+![Status](https://img.shields.io/badge/status-active-success?style=flat-square)
+
+---
+
+## What is MCP?
+
+**Model Context Protocol (MCP)** is an open standard that lets AI assistants (like Claude, Cursor, Copilot) connect to external tools and services — file systems, APIs, databases, browsers — through **MCP servers**.
+
+Think of MCP servers as plugins that give AI agents real-world capabilities.
+
+---
+
+## The Problem
+
+MCP servers run as **trusted processes** on your machine with access to:
+
+| Access | Risk |
+|---|---|
+| 🗂️ Your filesystem | Read `/etc/passwd`, steal SSH keys |
+| 🌐 Your network | SSRF to `169.254.169.254` (AWS metadata) |
+| 🔑 Your environment variables | Steal API keys, tokens, secrets |
+| ⚙️ Shell execution | Run arbitrary commands |
+
+**A malicious or compromised MCP server can silently exfiltrate your secrets, pivot to internal infrastructure, or execute code — and you'd never know.**
+
+This is not theoretical. A real SSRF vulnerability was found in an MCP OAuth HTTP transport implementation that allowed exactly this class of attack.
+
+---
+
+## How mcp-shield Fixes This
+
+mcp-shield sits **between your AI agent and the MCP server** as a policy enforcement layer.  
+Before any tool executes, mcp-shield evaluates it. If it's not allowed — it's blocked.
+
+```
+AI Agent
+   │
+   ▼
+mcp-shield /inspect
+   │
+   ├── Tool allowlist check     →  "read_secrets" not allowed → 🚫 BLOCK
+   ├── Blocked pattern check    →  "ssrf_fetch" is dangerous  → 🚫 BLOCK  
+   ├── Argument scanning        →  "169.254.169.254" in args  → 🚫 BLOCK
+   │
+   └── Passed all checks        →  ✅ ALLOW → MCP Server executes
+                                        │
+                                        ▼
+                                   Audit Log (SQLite)
+```
+
+Every decision — ALLOW or BLOCK — is logged with a full audit trail.
+
+---
+
+## Live Demo
+
+```bash
+# Start mcp-shield
+uvicorn runtime.api.main:app --reload
+
+# 🚫 Attempt secret theft → BLOCKED
+curl -X POST http://localhost:8000/inspect \
+  -H "Content-Type: application/json" \
+  -d '{"server_name":"evil","policy":"default","tool_call":{"tool_name":"read_secrets","arguments":{}}}'
+
+# → {"decision":"BLOCK","reason":"Tool 'read_secrets' is not in the allowed_tools list","blocked":true}
+
+# 🚫 Attempt SSRF to AWS metadata endpoint → BLOCKED
+curl -X POST http://localhost:8000/inspect \
+  -H "Content-Type: application/json" \
+  -d '{"server_name":"evil","policy":"default","tool_call":{"tool_name":"ssrf_fetch","arguments":{"url":"http://169.254.169.254/latest/meta-data/"}}}'
+
+# → {"decision":"BLOCK","reason":"Argument contains blocked pattern: '169.254.169.254'","blocked":true}
+
+# ✅ Safe tool → ALLOWED
+curl -X POST http://localhost:8000/inspect \
+  -H "Content-Type: application/json" \
+  -d '{"server_name":"safe","policy":"default","tool_call":{"tool_name":"safe_tool","arguments":{"name":"Sri"}}}'
+
+# → {"decision":"ALLOW","reason":"Passed all policy checks","blocked":false}
+```
+
+---
+
+## Key Features
+
+| Feature | Description |
+|---|---|
+| 🔒 **Policy Engine** | YAML-based allowlists + blocked patterns, per-server policies |
+| 🔍 **Argument Scanning** | Recursively scans nested args for SSRF, path traversal, dangerous patterns |
+| 📋 **Audit Logger** | Every decision logged to SQLite with timestamp, server, tool, reason |
+| 🐳 **Docker Sandbox** | Hardened containers: `--cap-drop=ALL`, `--network=none`, `--read-only` |
+| 📊 **Risk Scorer** | Scores MCP servers LOW / MEDIUM / HIGH based on tool capabilities |
+| 🖥️ **Live Dashboard** | Real-time web UI showing live block/allow feed at `/dashboard` |
+| ⚡ **CLI** | `mcpshield inspect`, `mcpshield audit`, `mcpshield stats`, `mcpshield risk` |
+
+---
+
+## Policies
+
+Policies are simple YAML files. Drop one in `policies/` and reference it by name.
+
+```yaml
+# policies/default.yaml
+allowed_tools:
+  - safe_tool
+  - list_files
+  - get_time
+
+block_network: true
+block_env_access: true
+
+blocked_arg_patterns:
+  - "169.254.169.254"   # AWS metadata SSRF
+  - "169.254.170.2"     # ECS metadata SSRF
+  - "localhost"
+  - "127.0.0.1"
+  - "/etc/passwd"
+  - "/etc/shadow"
+  - "file://"
+  - "gopher://"
+
+max_memory_mb: 256
+execution_timeout_seconds: 30
+```
+
+Switch policy per server:
+```bash
+POST /inspect  →  { "policy": "strict", ... }
+```
+
+---
+
+## Architecture
+
+```
+mcp-shield/
+├── runtime/
+│   ├── api/
+│   │   └── main.py            # FastAPI — /inspect /audit /sandbox /dashboard
+│   ├── policy_engine.py       # YAML policy loader + evaluator
+│   ├── audit_logger.py        # SQLite decision log
+│   ├── risk_scorer.py         # LOW/MEDIUM/HIGH risk scoring
+│   ├── cli.py                 # Typer CLI — inspect/audit/stats/risk
+│   ├── models.py              # Pydantic schemas
+│   └── sandbox/
+│       ├── base.py            # Abstract backend interface
+│       └── docker_backend.py  # Hardened Docker sandbox
+├── policies/
+│   ├── default.yaml           # Standard policy
+│   └── strict.yaml            # Zero-trust policy
+├── examples/
+│   ├── malicious_mcp_server/  # Demo attacker (SSRF + secret theft + exec)
+│   └── safe_mcp_server/       # Demo benign server
+└── tests/                     # 12 tests — all passing
+```
+
+---
+
+## Quickstart
+
+```bash
+# 1. Clone
+git clone https://github.com/srisowmya2000/mcp-shield
+cd mcp-shield
+
+# 2. Install
+python3 -m venv .venv && source .venv/bin/activate
+pip install fastapi uvicorn pydantic pydantic-settings mcp httpx pyyaml
+
+# 3. Start
+uvicorn runtime.api.main:app --reload
+
+# 4. Open
+# API docs  → http://localhost:8000/docs
+# Dashboard → http://localhost:8000/dashboard
+```
+
+---
+
+## CLI
+
+```bash
+# Inspect a tool call
+python3 -m runtime.cli inspect read_secrets
+# → 🚫 BLOCKED — Tool 'read_secrets' is not in the allowed_tools list
+
+# Score a server's risk
+python3 -m runtime.cli risk "read_secrets,ssrf_fetch,safe_tool"
+# → 🔴 HIGH RISK (score: 80)
+
+# View audit log
+python3 -m runtime.cli audit
+
+# View stats
+python3 -m runtime.cli stats
+# → Total: 6 | Allowed: 2 | Blocked: 4 (67% block rate)
+```
+
+---
+
+## API Reference
+
+| Endpoint | Method | Description |
+|---|---|---|
+| `/health` | GET | Service health check |
+| `/inspect` | POST | Evaluate tool call → ALLOW / BLOCK |
+| `/audit` | GET | Recent audit log entries |
+| `/audit/stats` | GET | Total / allowed / blocked counts |
+| `/risk/score` | POST | Score server risk by tool list |
+| `/sandbox/launch` | POST | Launch MCP server in hardened Docker |
+| `/sandbox/stop/{name}` | POST | Stop a running sandbox |
+| `/sandbox/list` | GET | List running sandboxes |
+| `/dashboard` | GET | Live real-time dashboard |
+
+---
+
+## Tests
+
+```bash
+pip install pytest
+pytest tests/ -v
+# 12 passed in 0.11s
+```
+
+Covers: tool allowlist blocking, SSRF argument detection, nested arg scanning, strict policy, edge cases.
+
+---
+
+## Roadmap
+
+- [x] Policy engine (allowlist + pattern scanning)
+- [x] Audit logger (SQLite)
+- [x] FastAPI REST surface
+- [x] Docker sandbox backend (hardened)
+- [x] Demo malicious MCP server
+- [x] Risk scorer (LOW / MEDIUM / HIGH)
+- [x] CLI (`mcpshield inspect`, `audit`, `stats`, `risk`)
+- [x] Real-time dashboard
+- [ ] Firecracker microVM backend
+- [ ] PyPI package (`pip install mcp-shield`)
+- [ ] `threat-model.md`
+
+---
+
+

mcpshield_runtime-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+runtime/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runtime/audit_logger.py,sha256=HVS3ofU_2VbplfnR_68V6hdgl78wrZqJwHDZbf8QFCQ,2697
+runtime/cli.py,sha256=cQHwYxpmDW_Q3tk7u-GZx_3liXa1mjBO6EjwM5FdoSc,5253
+runtime/models.py,sha256=TU75MNrxnfwLt0oYlP_JL2a-u0goR0YC1c2NB2sNjOk,564
+runtime/policy_engine.py,sha256=xid5ENKpMfRC0sCfupcN7y21s8iuK_3XUWzRzgEHFrA,2066
+runtime/risk_scorer.py,sha256=gTWBomzfd83H6j5rbKo_DRuh2vrYuv55NPjowQ3_fmM,996
+runtime/api/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runtime/api/main.py,sha256=wke6AuBC9LekwTgUX4330Nj4OTUhsM8uNZ6olVCdWug,2374
+runtime/sandbox/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runtime/sandbox/base.py,sha256=w4qmgAgVyPbrXkZNO3E_fYKZHQSe-49x3-kgXqtNyU0,363
+runtime/sandbox/docker_backend.py,sha256=dvTzHyPSyPQawaxBCxPws04UTYHPQdJEDh-HRttQ4GE,1865
+runtime/static/dashboard.html,sha256=qfoWAfvnh2L-WzVMGINYG2N01gaMrG2G0hbE3KDXj_g,6650
+mcpshield_runtime-0.1.0.dist-info/METADATA,sha256=qxng4-FrDFb7KDrXTWyq1badI6mmrQvC7HsMIXaCYb8,8700
+mcpshield_runtime-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcpshield_runtime-0.1.0.dist-info/entry_points.txt,sha256=mVjnVLyxraKjVbjTS-76kV_1rQwYp2Bm5TFYGqFbqKw,46
+mcpshield_runtime-0.1.0.dist-info/top_level.txt,sha256=-unY84bWeVaGfe3vfIlHYZmkol7p_-E1YKa_rnrmxAc,8
+mcpshield_runtime-0.1.0.dist-info/RECORD,,

mcpshield_runtime-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcpshield_runtime-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcpshield = runtime.cli:app

mcpshield_runtime-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+runtime

runtime/api/main.py

@@ -0,0 +1,73 @@
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from runtime.models import ToolCall, RunConfig, PolicyDecision
+from runtime.policy_engine import evaluate
+from runtime.audit_logger import log_decision, get_recent_logs, get_stats
+from runtime.sandbox.docker_backend import launch_sandbox, stop_sandbox, list_running_sandboxes
+
+app = FastAPI(title="mcp-shield", description="Secure MCP runtime with policy enforcement", version="0.1.0")
+
+class InspectRequest(BaseModel):
+    server_name: str
+    policy: str = "default"
+    tool_call: ToolCall
+
+class LaunchRequest(BaseModel):
+    server_name: str
+    image: str
+    policy: str = "default"
+    env_vars: dict[str, str] = {}
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "service": "mcp-shield", "version": "0.1.0"}
+
+@app.post("/inspect")
+def inspect_tool_call(req: InspectRequest):
+    try:
+        result = evaluate(req.tool_call, req.policy)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    log_decision(req.server_name, req.tool_call, result)
+    return {"server": req.server_name, "tool": req.tool_call.tool_name,
+            "policy": req.policy, "decision": result.decision,
+            "reason": result.reason, "blocked": result.decision == PolicyDecision.BLOCK}
+
+@app.get("/audit")
+def audit_log(limit: int = 50):
+    return {"logs": get_recent_logs(limit)}
+
+@app.get("/audit/stats")
+def audit_stats():
+    return get_stats()
+
+@app.post("/sandbox/launch")
+def launch(req: LaunchRequest):
+    config = RunConfig(server_name=req.server_name, image=req.image,
+                       policy=req.policy, env_vars=req.env_vars)
+    return launch_sandbox(config)
+
+@app.post("/sandbox/stop/{server_name}")
+def stop(server_name: str):
+    return stop_sandbox(server_name)
+
+@app.get("/sandbox/list")
+def list_sandboxes():
+    return {"sandboxes": list_running_sandboxes()}
+
+from runtime.risk_scorer import score_server
+
+class RiskRequest(BaseModel):
+    tool_names: list[str]
+
+@app.post("/risk/score")
+def risk_score(req: RiskRequest):
+    return score_server(req.tool_names)
+
+from fastapi.responses import FileResponse
+from pathlib import Path
+
+@app.get("/dashboard", tags=["dashboard"])
+def dashboard():
+    """Live real-time decision dashboard."""
+    return FileResponse(Path(__file__).parent.parent / "static" / "dashboard.html")

runtime/audit_logger.py

@@ -0,0 +1,67 @@
+import sqlite3
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from runtime.models import ToolCall, PolicyResult, PolicyDecision
+
+DB_PATH = Path(__file__).parent.parent / "reports" / "audit.db"
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s", datefmt="%Y-%m-%dT%H:%M:%S")
+logger = logging.getLogger("mcp-shield")
+
+def init_db():
+    DB_PATH.parent.mkdir(exist_ok=True)
+    conn = sqlite3.connect(DB_PATH)
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS audit_log (
+            id          INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp   TEXT NOT NULL,
+            server_name TEXT NOT NULL,
+            tool_name   TEXT NOT NULL,
+            arguments   TEXT,
+            decision    TEXT NOT NULL,
+            reason      TEXT NOT NULL
+        )
+    """)
+    conn.commit()
+    conn.close()
+
+def log_decision(server_name: str, tool_call: ToolCall, result: PolicyResult) -> None:
+    init_db()
+    timestamp = datetime.now(timezone.utc).isoformat()
+    icon = "✅" if result.decision == PolicyDecision.ALLOW else "🚫"
+    entry = {"timestamp": timestamp, "server": server_name, "tool": tool_call.tool_name,
+             "decision": result.decision.value, "reason": result.reason}
+    logger.info(f"{icon} {json.dumps(entry)}")
+    conn = sqlite3.connect(DB_PATH)
+    conn.execute("""
+        INSERT INTO audit_log (timestamp, server_name, tool_name, arguments, decision, reason)
+        VALUES (?, ?, ?, ?, ?, ?)
+    """, (timestamp, server_name, tool_call.tool_name, json.dumps(tool_call.arguments),
+          result.decision.value, result.reason))
+    conn.commit()
+    conn.close()
+
+def get_recent_logs(limit: int = 50) -> list[dict]:
+    if not DB_PATH.exists():
+        return []
+    conn = sqlite3.connect(DB_PATH)
+    rows = conn.execute("""
+        SELECT timestamp, server_name, tool_name, arguments, decision, reason
+        FROM audit_log ORDER BY id DESC LIMIT ?
+    """, (limit,)).fetchall()
+    conn.close()
+    return [{"timestamp": r[0], "server": r[1], "tool": r[2],
+             "arguments": json.loads(r[3]) if r[3] else {}, "decision": r[4], "reason": r[5]}
+            for r in rows]
+
+def get_stats() -> dict:
+    if not DB_PATH.exists():
+        return {"total": 0, "allowed": 0, "blocked": 0}
+    conn = sqlite3.connect(DB_PATH)
+    total = conn.execute("SELECT COUNT(*) FROM audit_log").fetchone()[0]
+    allowed = conn.execute("SELECT COUNT(*) FROM audit_log WHERE decision='ALLOW'").fetchone()[0]
+    blocked = conn.execute("SELECT COUNT(*) FROM audit_log WHERE decision='BLOCK'").fetchone()[0]
+    conn.close()
+    return {"total": total, "allowed": allowed, "blocked": blocked}

runtime/cli.py

@@ -0,0 +1,149 @@
+import typer
+import httpx
+import json
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich import box
+
+app = typer.Typer(
+    name="mcpshield",
+    help="🛡️  mcp-shield — secure MCP runtime CLI",
+    add_completion=False
+)
+console = Console()
+BASE = "http://localhost:8000"
+
+
+@app.command()
+def inspect(
+    tool: str = typer.Argument(..., help="Tool name to inspect"),
+    policy: str = typer.Option("default", "--policy", "-p", help="Policy to evaluate against"),
+    server: str = typer.Option("cli", "--server", "-s", help="Server name label"),
+    args: str = typer.Option("{}", "--args", "-a", help='Tool arguments as JSON string'),
+):
+    """Inspect a tool call against a policy. Returns ALLOW or BLOCK."""
+    try:
+        arguments = json.loads(args)
+    except json.JSONDecodeError:
+        console.print("[red]Error: --args must be valid JSON[/red]")
+        raise typer.Exit(1)
+
+    try:
+        r = httpx.post(f"{BASE}/inspect", json={
+            "server_name": server,
+            "policy": policy,
+            "tool_call": {"tool_name": tool, "arguments": arguments}
+        })
+        data = r.json()
+        if data["blocked"]:
+            console.print(Panel(
+                f"[bold red]🚫 BLOCKED[/bold red]\n\n"
+                f"Tool:    [yellow]{tool}[/yellow]\n"
+                f"Policy:  {policy}\n"
+                f"Reason:  {data['reason']}",
+                title="mcp-shield decision", border_style="red"
+            ))
+        else:
+            console.print(Panel(
+                f"[bold green]✅ ALLOWED[/bold green]\n\n"
+                f"Tool:    [yellow]{tool}[/yellow]\n"
+                f"Policy:  {policy}\n"
+                f"Reason:  {data['reason']}",
+                title="mcp-shield decision", border_style="green"
+            ))
+    except httpx.ConnectError:
+        console.print("[red]Error: Cannot connect to mcp-shield API. Is it running?[/red]")
+        console.print("[dim]Run: uvicorn runtime.api.main:app --reload[/dim]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def audit(
+    limit: int = typer.Option(20, "--limit", "-n", help="Number of recent entries to show"),
+):
+    """Show recent audit log entries."""
+    try:
+        r = httpx.get(f"{BASE}/audit?limit={limit}")
+        logs = r.json()["logs"]
+
+        if not logs:
+            console.print("[dim]No audit entries yet.[/dim]")
+            return
+
+        table = Table(box=box.ROUNDED, show_header=True, header_style="bold cyan")
+        table.add_column("Time", style="dim", width=20)
+        table.add_column("Server", width=16)
+        table.add_column("Tool", width=18)
+        table.add_column("Decision", width=10)
+        table.add_column("Reason")
+
+        for log in logs:
+            decision_str = (
+                "[bold red]🚫 BLOCK[/bold red]"
+                if log["decision"] == "BLOCK"
+                else "[bold green]✅ ALLOW[/bold green]"
+            )
+            table.add_row(
+                log["timestamp"][:19].replace("T", " "),
+                log["server"],
+                log["tool"],
+                decision_str,
+                log["reason"][:55] + ("…" if len(log["reason"]) > 55 else "")
+            )
+
+        console.print(table)
+    except httpx.ConnectError:
+        console.print("[red]Error: Cannot connect to mcp-shield API.[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def stats():
+    """Show audit statistics — total, allowed, blocked."""
+    try:
+        r = httpx.get(f"{BASE}/audit/stats")
+        data = r.json()
+        total = data["total"]
+        allowed = data["allowed"]
+        blocked = data["blocked"]
+        pct = f"{(blocked/total*100):.0f}%" if total > 0 else "0%"
+
+        console.print(Panel(
+            f"[bold]Total decisions:[/bold]  {total}\n"
+            f"[green]✅ Allowed:[/green]        {allowed}\n"
+            f"[red]🚫 Blocked:[/red]        {blocked}  ({pct} block rate)",
+            title="🛡️  mcp-shield audit stats",
+            border_style="cyan"
+        ))
+    except httpx.ConnectError:
+        console.print("[red]Error: Cannot connect to mcp-shield API.[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def risk(
+    tools: str = typer.Argument(..., help="Comma-separated list of tool names to score"),
+):
+    """Score an MCP server's risk level based on its tools."""
+    tool_list = [t.strip() for t in tools.split(",")]
+    try:
+        r = httpx.post(f"{BASE}/risk/score", json={"tool_names": tool_list})
+        data = r.json()
+
+        color = {"HIGH": "red", "MEDIUM": "yellow", "LOW": "green"}[data["risk_level"]]
+        console.print(Panel(
+            f"[bold {color}]{data['risk_level']} RISK (score: {data['risk_score']})[/bold {color}]\n\n"
+            f"[red]High-risk tools:[/red]   {data['high_risk_tools'] or 'none'}\n"
+            f"[yellow]Medium-risk tools:[/yellow] {data['medium_risk_tools'] or 'none'}\n\n"
+            f"[dim]{data['recommendation']}[/dim]",
+            title="🛡️  mcp-shield risk score",
+            border_style=color
+        ))
+    except httpx.ConnectError:
+        console.print("[red]Error: Cannot connect to mcp-shield API.[/red]")
+        raise typer.Exit(1)
+
+
+if __name__ == "__main__":
+    app()

runtime/models.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel
+from typing import Any, Optional
+from enum import Enum
+
+class PolicyDecision(str, Enum):
+    ALLOW = "ALLOW"
+    BLOCK = "BLOCK"
+
+class ToolCall(BaseModel):
+    tool_name: str
+    arguments: dict[str, Any] = {}
+
+class PolicyResult(BaseModel):
+    decision: PolicyDecision
+    reason: str
+
+class RunConfig(BaseModel):
+    server_name: str
+    image: str
+    policy: str = "default"
+    env_vars: dict[str, str] = {}
+
+class SandboxStatus(BaseModel):
+    container_id: Optional[str]
+    server_name: str
+    status: str
+    policy: str

runtime/policy_engine.py

@@ -0,0 +1,56 @@
+import yaml
+from pathlib import Path
+from runtime.models import ToolCall, PolicyResult, PolicyDecision
+
+POLICIES_DIR = Path(__file__).parent.parent / "policies"
+
+def load_policy(name: str) -> dict:
+    path = POLICIES_DIR / f"{name}.yaml"
+    if not path.exists():
+        raise FileNotFoundError(f"Policy file not found: {name}.yaml")
+    with open(path) as f:
+        return yaml.safe_load(f)
+
+def evaluate(tool_call: ToolCall, policy_name: str = "default") -> PolicyResult:
+    policy = load_policy(policy_name)
+    allowed_tools = policy.get("allowed_tools", [])
+    blocked_patterns = policy.get("blocked_tool_patterns", [])
+    blocked_arg_patterns = policy.get("blocked_arg_patterns", [])
+
+    if tool_call.tool_name not in allowed_tools:
+        return PolicyResult(
+            decision=PolicyDecision.BLOCK,
+            reason=f"Tool '{tool_call.tool_name}' is not in the allowed_tools list"
+        )
+
+    for pattern in blocked_patterns:
+        if pattern.lower() in tool_call.tool_name.lower():
+            return PolicyResult(
+                decision=PolicyDecision.BLOCK,
+                reason=f"Tool name matches blocked pattern: '{pattern}'"
+            )
+
+    all_values = _flatten_args(tool_call.arguments)
+    for val in all_values:
+        for pattern in blocked_arg_patterns:
+            if pattern.lower() in val.lower():
+                return PolicyResult(
+                    decision=PolicyDecision.BLOCK,
+                    reason=f"Argument contains blocked pattern: '{pattern}' — possible SSRF or path traversal"
+                )
+
+    return PolicyResult(decision=PolicyDecision.ALLOW, reason="Passed all policy checks")
+
+def _flatten_args(args: dict, depth: int = 0) -> list[str]:
+    if depth > 5:
+        return []
+    result = []
+    for val in args.values():
+        if isinstance(val, dict):
+            result.extend(_flatten_args(val, depth + 1))
+        elif isinstance(val, list):
+            for item in val:
+                result.append(str(item))
+        else:
+            result.append(str(val))
+    return result

runtime/risk_scorer.py

@@ -0,0 +1,30 @@
+from runtime.models import PolicyDecision
+
+HIGH_RISK_TOOLS = {"read_secrets", "ssrf_fetch", "exec_command", "shell_exec", "delete_file", "write_file"}
+MEDIUM_RISK_TOOLS = {"read_file", "list_files", "network_request", "http_get"}
+
+def score_server(tool_names: list[str]) -> dict:
+    high = [t for t in tool_names if t in HIGH_RISK_TOOLS]
+    medium = [t for t in tool_names if t in MEDIUM_RISK_TOOLS]
+
+    if high:
+        level = "HIGH"
+        score = 90 - (10 * max(0, 3 - len(high)))
+    elif medium:
+        level = "MEDIUM"
+        score = 50
+    else:
+        level = "LOW"
+        score = 10
+
+    return {
+        "risk_level": level,
+        "risk_score": score,
+        "high_risk_tools": high,
+        "medium_risk_tools": medium,
+        "recommendation": {
+            "HIGH": "Do not run without strict policy. Use isolated network.",
+            "MEDIUM": "Run with default policy. Monitor closely.",
+            "LOW": "Safe to run with standard policy.",
+        }[level]
+    }

runtime/sandbox/base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+from runtime.models import RunConfig, SandboxStatus
+
+class SandboxBackend(ABC):
+    @abstractmethod
+    def launch(self, config: RunConfig) -> SandboxStatus:
+        pass
+
+    @abstractmethod
+    def stop(self, server_name: str) -> dict:
+        pass
+
+    @abstractmethod
+    def list_running(self) -> list[dict]:
+        pass

runtime/sandbox/docker_backend.py

@@ -0,0 +1,43 @@
+import subprocess
+import json
+from runtime.models import RunConfig, SandboxStatus
+
+def launch_sandbox(config: RunConfig) -> SandboxStatus:
+    cmd = [
+        "docker", "run", "--rm", "--detach",
+        "--name", f"mcp-shield-{config.server_name}",
+        "--memory=256m", "--cpus=0.5", "--pids-limit=64",
+        "--cap-drop=ALL", "--no-new-privileges", "--read-only",
+        "--network=none",
+        "--tmpfs=/tmp:rw,noexec,nosuid,size=64m",
+    ]
+    for key, val in config.env_vars.items():
+        cmd += ["--env", f"{key}={val}"]
+    cmd.append(config.image)
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=15)
+        if result.returncode == 0:
+            return SandboxStatus(container_id=result.stdout.strip()[:12],
+                                 server_name=config.server_name, status="running", policy=config.policy)
+        return SandboxStatus(container_id=None, server_name=config.server_name,
+                             status=f"failed: {result.stderr.strip()}", policy=config.policy)
+    except FileNotFoundError:
+        return SandboxStatus(container_id=None, server_name=config.server_name,
+                             status="docker not found", policy=config.policy)
+
+def stop_sandbox(server_name: str) -> dict:
+    result = subprocess.run(["docker", "stop", f"mcp-shield-{server_name}"],
+                            capture_output=True, text=True)
+    return {"stopped": result.returncode == 0}
+
+def list_running_sandboxes() -> list[dict]:
+    result = subprocess.run(
+        ["docker", "ps", "--filter", "name=mcp-shield-", "--format", "json"],
+        capture_output=True, text=True)
+    containers = []
+    for line in result.stdout.strip().splitlines():
+        try:
+            containers.append(json.loads(line))
+        except json.JSONDecodeError:
+            pass
+    return containers

runtime/static/dashboard.html

@@ -0,0 +1,151 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>mcp-shield dashboard</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body { background: #0d1117; color: #e6edf3; font-family: 'Segoe UI', monospace; }
+  header { background: #161b22; border-bottom: 1px solid #30363d; padding: 16px 32px; display: flex; align-items: center; gap: 12px; }
+  header h1 { font-size: 20px; font-weight: 700; }
+  header span { font-size: 13px; color: #8b949e; }
+  .badge { background: #1f6feb; color: white; font-size: 11px; padding: 2px 8px; border-radius: 12px; }
+
+  .stats { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; padding: 24px 32px; }
+  .stat-card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 20px; }
+  .stat-card .label { font-size: 12px; color: #8b949e; text-transform: uppercase; letter-spacing: 1px; margin-bottom: 8px; }
+  .stat-card .value { font-size: 36px; font-weight: 700; }
+  .stat-card.total .value { color: #e6edf3; }
+  .stat-card.allowed .value { color: #3fb950; }
+  .stat-card.blocked .value { color: #f85149; }
+  .stat-card .sub { font-size: 12px; color: #8b949e; margin-top: 4px; }
+
+  .feed-section { padding: 0 32px 32px; }
+  .feed-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 12px; }
+  .feed-header h2 { font-size: 15px; font-weight: 600; }
+  .live-dot { width: 8px; height: 8px; background: #3fb950; border-radius: 50%; display: inline-block; margin-right: 6px; animation: pulse 1.5s infinite; }
+  @keyframes pulse { 0%,100% { opacity:1; } 50% { opacity:0.3; } }
+
+  .feed { background: #161b22; border: 1px solid #30363d; border-radius: 8px; overflow: hidden; }
+  .feed-row { display: grid; grid-template-columns: 160px 140px 160px 100px 1fr; gap: 12px; padding: 10px 16px; border-bottom: 1px solid #21262d; font-size: 13px; align-items: center; transition: background 0.3s; }
+  .feed-row:last-child { border-bottom: none; }
+  .feed-row.new-block { animation: flashRed 0.6s ease; }
+  .feed-row.new-allow { animation: flashGreen 0.6s ease; }
+  @keyframes flashRed { 0% { background: #3d1a1a; } 100% { background: transparent; } }
+  @keyframes flashGreen { 0% { background: #1a3d1a; } 100% { background: transparent; } }
+  .feed-header-row { background: #0d1117; color: #8b949e; font-size: 11px; text-transform: uppercase; letter-spacing: 1px; }
+  .decision-block { color: #f85149; font-weight: 600; }
+  .decision-allow { color: #3fb950; font-weight: 600; }
+  .time { color: #8b949e; }
+  .server { color: #79c0ff; }
+  .tool { color: #ffa657; font-family: monospace; }
+  .reason { color: #8b949e; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+
+  .empty { text-align: center; padding: 48px; color: #8b949e; }
+  .refresh-info { text-align: right; font-size: 11px; color: #30363d; padding: 8px 32px; }
+</style>
+</head>
+<body>
+
+<header>
+  <span>🛡️</span>
+  <h1>mcp-shield</h1>
+  <span class="badge">LIVE</span>
+  <span style="margin-left:auto; font-size:12px; color:#8b949e;" id="last-updated">—</span>
+</header>
+
+<div class="stats">
+  <div class="stat-card total">
+    <div class="label">Total Decisions</div>
+    <div class="value" id="stat-total">—</div>
+    <div class="sub">all time</div>
+  </div>
+  <div class="stat-card allowed">
+    <div class="label">✅ Allowed</div>
+    <div class="value" id="stat-allowed">—</div>
+    <div class="sub" id="stat-allow-pct">—</div>
+  </div>
+  <div class="stat-card blocked">
+    <div class="label">🚫 Blocked</div>
+    <div class="value" id="stat-blocked">—</div>
+    <div class="sub" id="stat-block-pct">—</div>
+  </div>
+</div>
+
+<div class="feed-section">
+  <div class="feed-header">
+    <h2><span class="live-dot"></span>Live Decision Feed</h2>
+    <span style="font-size:12px; color:#8b949e;">auto-refreshes every 2s</span>
+  </div>
+  <div class="feed">
+    <div class="feed-row feed-header-row">
+      <span>Time</span><span>Server</span><span>Tool</span><span>Decision</span><span>Reason</span>
+    </div>
+    <div id="feed-body">
+      <div class="empty">No decisions yet — start sending tool calls to /inspect</div>
+    </div>
+  </div>
+</div>
+
+<script>
+  let prevTotal = 0;
+  let prevIds = new Set();
+
+  async function refresh() {
+    try {
+      const [statsRes, logsRes] = await Promise.all([
+        fetch('/audit/stats'),
+        fetch('/audit?limit=30')
+      ]);
+      const stats = await statsRes.json();
+      const logs = (await logsRes.json()).logs;
+
+      // Update stats
+      const total = stats.total || 0;
+      const allowed = stats.allowed || 0;
+      const blocked = stats.blocked || 0;
+      document.getElementById('stat-total').textContent = total;
+      document.getElementById('stat-allowed').textContent = allowed;
+      document.getElementById('stat-blocked').textContent = blocked;
+      document.getElementById('stat-allow-pct').textContent =
+        total > 0 ? `${((allowed/total)*100).toFixed(0)}% of decisions` : '—';
+      document.getElementById('stat-block-pct').textContent =
+        total > 0 ? `${((blocked/total)*100).toFixed(0)}% block rate` : '—';
+      document.getElementById('last-updated').textContent =
+        'Updated ' + new Date().toLocaleTimeString();
+
+      // Update feed
+      const feedBody = document.getElementById('feed-body');
+      if (!logs || logs.length === 0) {
+        feedBody.innerHTML = '<div class="empty">No decisions yet — start sending tool calls to /inspect</div>';
+        return;
+      }
+
+      const newIds = new Set(logs.map((l, i) => `${l.timestamp}-${l.tool}-${i}`));
+      feedBody.innerHTML = logs.map((log, i) => {
+        const id = `${log.timestamp}-${log.tool}-${i}`;
+        const isNew = !prevIds.has(id) && prevIds.size > 0;
+        const isBlock = log.decision === 'BLOCK';
+        const time = log.timestamp.replace('T',' ').substring(0,19);
+        const animClass = isNew ? (isBlock ? 'new-block' : 'new-allow') : '';
+        return `<div class="feed-row ${animClass}">
+          <span class="time">${time}</span>
+          <span class="server">${log.server}</span>
+          <span class="tool">${log.tool}</span>
+          <span class="${isBlock ? 'decision-block' : 'decision-allow'}">${isBlock ? '🚫 BLOCK' : '✅ ALLOW'}</span>
+          <span class="reason" title="${log.reason}">${log.reason}</span>
+        </div>`;
+      }).join('');
+
+      prevIds = newIds;
+    } catch(e) {
+      document.getElementById('last-updated').textContent = 'API unreachable';
+    }
+  }
+
+  refresh();
+  setInterval(refresh, 2000);
+</script>
+</body>
+</html>