mcp-ztgateway 0.2.2

Zero-trust security gateway for MCP (Model Context Protocol) tool servers — static scanning, sandbox behavioural profiling, and runtime policy enforcement.

MCP Zero-Trust Gateway

A security gateway that sits between an LLM agent and the MCP (Model Context Protocol) tool servers it uses, built on the principle that no tool server is trusted by default. Every tool is inspected before it is allowed in, profiled in a sandbox to see what it actually does, constrained by least-privilege policy, and monitored at runtime.

It runs entirely on your machine, ensuring privacy and security. The trust store is a local SQLite file and no telemetry is sent anywhere.

The Vulnerability

An LLM agent discovers tools by reading each MCP server's self-description (tools/list). It then calls them (tools/call) with its own privileges. The agent natively treats the server's description as the absolute truth.

That assumption is a critical vulnerability: a malicious server (via a supply chain attack or direct compromise) can hide instructions in its description (Prompt Poisoning) or perform actions its manifest never declared (e.g., reading SSH keys while claiming to just fetch weather). This Gateway eliminates that default trust.

Threat Scope & Process Ownership

This Gateway is designed to protect your system from untrusted MCP servers by sandboxing them at the operating-system level.

To enforce this kernel-level protection (via strace and seccomp), the Gateway must be the process that spawns the tool.

The "Process Ownership" Boundary:

• Supported: Any MCP server that the Gateway launches as a child process. This includes nearly all stdio tools (e.g., npx, python scripts) and any local HTTP/SSE servers if the Gateway issues the spawn command.
• Unsupported (Cannot be Sandboxed): Any server running remotely, OR any local server launched by an external application. For example, the native Figma Desktop app exposes an SSE server on 127.0.0.1. Because Figma launched that process—not the Gateway—we cannot attach a kernel profiler to it or sandbox it at exec-time.

Comparison with Protocol-Layer Defenses

Our Gateway enforces security at the process boundary (watching syscalls). This makes it blind to servers it doesn't own (like native desktop apps). Conversely, defenses like ClawGuard enforce security at the protocol boundary (inspecting JSON-RPC messages). ClawGuard operates identically whether the tool is a local subprocess, a foreign-launched SSE server, or a remote HTTP API, because it never touches the execution environment. Together, process-level and protocol-level defenses offer complementary protection with inverse blind spots.

Core Architecture

The Zero-Trust Gateway implements a multi-layered defensive architecture:

1. L1 Static Scanner: Intercepts the tools/list manifest during onboarding. It parses the tool's natural language description and inputSchema to automatically infer Declared Capabilities (e.g., inferring FILE_ACCESS if the tool describes itself as a file reader). It also uses heuristic rules to detect and reject Prompt Poisoning attempts in the manifest.
2. L2 Dynamic Sandbox (Live Profiling): The tool is executed in a highly constrained Docker environment. The Gateway uses strace as the entrypoint to capture every system call the tool attempts (e.g., open, socket, execve). These syscalls are mapped to Observed Capabilities.
3. Automated Seccomp Compiler: Directly addressing the gap in modern dynamic analysis, the Gateway acts as a policy compiler. It parses the unfiltered strace logs to extract every unique syscall the tool required, synthesizing a strict, deployment-ready Docker seccomp.json profile representing the exact behavioral boundaries of the tool.
4. Zero-Trust Comparator: Compares the Observed Capabilities against the Declared Capabilities.
   • Match: If the tool operates strictly within its declared boundaries, the Gateway issues an allow verdict and outputs the custom seccomp.json.
   • Mismatch: If the tool attempts an undeclared action, the Gateway immediately issues a quarantine verdict.
5. Runtime Proxy: Every subsequent tool call passes through the gateway. The Gateway dynamically injects the generated seccomp.json into the container execution, enforcing the exact behavioral profile at the OS kernel level.

Installation & Setup

This repository is optimized for local development and execution on Windows/WSL2 or Linux environments. Docker Desktop is required to run the L2_Sandbox dynamic profiling layer.

Quick Start (Windows)

We provide an automated PowerShell script to install dependencies, set up the environment, and start the Uvicorn gateway server:

.\start_gateway.ps1

Installation & Setup

You can install the Zero-Trust Gateway directly via PyPI, or run it locally from source.

Option 1: Install via PyPI (Recommended)

pip install mcp-ztgateway

Once installed, you can start the gateway using the CLI:

mcp-ztgateway --port 8000

Option 2: Run Locally (Development)

# Clone the repository
git clone https://github.com/nabrahma/MCP_Zero-Trust_Gateway_BTP.git
cd MCP_Zero-Trust_Gateway_BTP

# Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install requirements
pip install -r requirements.txt

# Start the gateway
./start_gateway.ps1

How to Use the Gateway

Once the gateway is running on http://127.0.0.1:8000, all MCP tools must be registered and verified through it before an LLM agent is permitted to use them.

Onboarding a New Tool

To register a tool, you send a JSON payload to the /register endpoint containing the Docker command required to run the MCP Server.

Important: The target Docker image must have strace installed to support the live dynamic profiling phase.

Example payload to onboard a legitimate tool:

POST /register
{
  "name": "read_file",
  "command": ["docker", "run", "-i", "--rm", "real-mcp-image", "mcp-server-filesystem", "/app"],
  "image": "real-mcp-image",
  "env": {},
  "test_tool": "read_file",
  "test_args": {"path": "/app/package.json"}
}

The Gateway will automatically:

1. Scan the tool's manifest for poisoning.
2. Execute the tool in the sandbox using strace to intercept its system calls.
3. Compare the actions it took against what it declared in its description.
4. Return a Verdict (Allow, Deny, or Quarantine).

Using the Gateway in Docker

You can also run the Gateway and the accompanying Dashboard using Docker Compose:

docker-compose up --build
# Gateway API -> http://localhost:8000
# Dashboard   -> http://localhost:5173

(Note: Live sandbox profiling requires executing Docker commands, which relies on the host's Docker daemon. The provided gateway service requires appropriate volume mounts to execute properly).

Status and Limitations

This project is a final-year B.Tech project focusing on proving the empirical viability of a Zero-Trust architecture for LLM Tool use.

• Dynamic Profiling Evasion: A highly sophisticated tool that stays completely dormant during profiling, specifically detects the sandbox, or only misbehaves on unseen inputs will not be caught during the onboarding phase. This is an inherent limitation of dynamic analysis.
• Coarse Enforcement: Syscall interception maps to broad capability classes (e.g., FILE_ACCESS), not exact semantics ("reads of .env specifically"). Granular per-path decisions are handled by upper-level policy layers.

Tech Stack

• Backend Core: Python, FastAPI
• Sandboxing: Docker, strace, seccomp
• Data/State: SQLite

License

MIT — see LICENSE.