Metadata-Version: 2.4
Name: mcp-ztgateway
Version: 0.2.0
Summary: Zero-trust security gateway for MCP (Model Context Protocol) tool servers — static scanning, sandbox behavioural profiling, and runtime policy enforcement.
License: MIT
Project-URL: Homepage, https://github.com/nabrahma/MCP_Zero-Trust_Gateway_BTP
Project-URL: Repository, https://github.com/nabrahma/MCP_Zero-Trust_Gateway_BTP
Project-URL: Issues, https://github.com/nabrahma/MCP_Zero-Trust_Gateway_BTP/issues
Keywords: mcp,security,zero-trust,gateway,llm,agent,sandbox,seccomp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Framework :: FastAPI
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn>=0.30
Requires-Dist: mcp[cli]>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: click>=8.0
Requires-Dist: httpx>=0.27
Provides-Extra: audit
Requires-Dist: pip-audit>=2.7; extra == "audit"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# 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.

## 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:

```powershell
.\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)
```bash
pip install mcp-ztgateway
```
Once installed, you can start the gateway using the CLI:
```bash
mcp-ztgateway --port 8000
```

### Option 2: Run Locally (Development)
```bash
# 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:

```json
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:

```bash
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](LICENSE).
