Metadata-Version: 2.4
Name: agentsec-gateway
Version: 0.1.1
Summary: Security gateway for MCP (Model Context Protocol) server connections
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: agentsec-core>=0.1.0
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.3.0; extra == "dev"

# MCP Security Gateway

Security gateway that proxies MCP (Model Context Protocol) server connections with real-time scanning, audit logging, and policy enforcement.

Part of the [AgentSec](https://github.com/agentsec) suite -- open-source security primitives for AI agents.

## Install

```bash
pip install agentsec-gateway
```

> **Premium:** Get IP reputation database, advanced data flow analytics, and multi-server policy orchestration at [zazmatt.gumroad.com/l/hjpwk](https://zazmatt.gumroad.com/l/hjpwk)

## Quick Start

```bash
# Patch .mcp.json to route all MCP servers through the gateway
mcp-gateway install

# That's it. All MCP traffic is now scanned and logged.
```

## How It Works

```
Claude Code                MCP Gateway              MCP Server
    |                          |                         |
    |--- JSON-RPC request ---->|                         |
    |                          |-- scan for secrets ---->|
    |                          |-- scan for injections ->|
    |                          |-- log to audit trail -->|
    |                          |--- forward request ---->|
    |                          |                         |
    |                          |<--- response -----------|
    |                          |-- scan for leakage ---->|
    |                          |-- log to audit trail -->|
    |<--- forward response ----|                         |
```

The gateway wraps each MCP server command in `.mcp.json` so all stdio traffic passes through a transparent proxy. It scans for:

- **Secret leakage** -- API keys, tokens, passwords, PII in tool parameters
- **Prompt injection** -- attempts to override system instructions via tool arguments
- **Path traversal** -- `../etc/passwd`, `~/.ssh/` style attacks
- **Command injection** -- shell metacharacters, subshell execution
- **Data exfiltration** -- secrets in server responses flowing back to Claude

## CLI Reference

| Command | Description |
|---------|-------------|
| `mcp-gateway install` | Patch `.mcp.json` to route through gateway |
| `mcp-gateway uninstall` | Restore original `.mcp.json` |
| `mcp-gateway proxy --server NAME -- CMD` | Run as proxy (internal, called by patched config) |
| `mcp-gateway scan` | List configured servers and their status |
| `mcp-gateway audit [-n 20] [--server NAME]` | View audit log |
| `mcp-gateway report` | Generate security report (reputation + data flow) |
| `mcp-gateway status` | Show install status and server list |

## Configuration

Create `.mcp-gateway/policy.yaml` to define per-server policies:

```yaml
servers:
  filesystem:
    allowed_tools: ["read_*", "list_*", "search_*"]
    blocked_tools: ["write_*", "delete_*"]
    max_calls_per_minute: 30
    data_classification: internal

  gmail:
    allowed_tools: ["gmail_search*", "gmail_read*"]
    blocked_tools: ["gmail_create_draft", "gmail_send*"]
    max_calls_per_minute: 10
    data_classification: confidential
```

### Policy Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `allowed_tools` | list[str] | `[]` (all) | Glob patterns for allowed tools |
| `blocked_tools` | list[str] | `[]` | Glob patterns for blocked tools |
| `max_calls_per_minute` | int | `60` | Rate limit per server |
| `data_classification` | str | `internal` | `public`, `internal`, `confidential` |

## Security Features

- **Secret scanning** -- 23 pattern rules covering API keys, tokens, passwords, PII (SSN, credit cards)
- **High-entropy detection** -- Shannon entropy analysis catches unknown secret formats
- **Prompt injection detection** -- catches "ignore previous instructions", developer mode, system tag injection
- **Path traversal detection** -- blocks `../`, `/etc/passwd`, `~/.ssh/` access attempts
- **Command injection detection** -- catches shell metacharacters, subshells, pipe-to-bash
- **Tamper-proof audit log** -- SHA-256 hash chain on every log entry
- **Server reputation tracking** -- trust scores degrade on violations
- **Data flow monitoring** -- per-server byte counting with anomaly detection

## Architecture

Built on [agentsec-core](../agentsec-core/) for scanning, policy, and audit primitives. Uses synchronous threading for the stdio proxy (no asyncio complexity).

## Free vs Premium

| Feature | Free (OSS) | Premium |
|---------|:----------:|:-------:|
| Transparent MCP proxy | Yes | Yes |
| Secret scanning (23 patterns) | Yes | Yes |
| Prompt injection detection | Yes | Yes |
| Tamper-proof audit log | Yes | Yes |
| IP reputation database | -- | Yes |
| Data flow analytics dashboard | -- | Yes |
| Multi-server policy orchestration | -- | Yes |
| Rate limiting with burst control | -- | Yes |
| Priority support | -- | Yes |

[Get Premium -- $10](https://zazmatt.gumroad.com/l/hjpwk)

## Development

```bash
pip install -e ".[dev]"
pytest
ruff check .
```

## License

MIT
