mcpsafetywarden

<!-- mcp-name: io.github.gautamvarmadatla/mcpsafetywarden -->
<p align="center">
  <img src="assets/logo.png" alt="MCP Safety Warden" width="1080"/>
</p>

MCP safety warden is a proxy server that wraps any MCP server and adds behavioral profiling, security scanning, risk gating, and safe execution to its tools.

[![PyPI](https://img.shields.io/pypi/v/mcpsafetywarden)](https://pypi.org/project/mcpsafetywarden/)
[![Python](https://img.shields.io/pypi/pyversions/mcpsafetywarden)](https://pypi.org/project/mcpsafetywarden/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/mcpsafetywarden)](https://pypi.org/project/mcpsafetywarden/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
[![CI](https://github.com/gautamvarmadatla/mcpsafetywarden/actions/workflows/ci.yml/badge.svg)](https://github.com/gautamvarmadatla/mcpsafetywarden/actions/workflows/ci.yml)
[![CodeQL](https://github.com/gautamvarmadatla/mcpsafetywarden/actions/workflows/codeql.yml/badge.svg)](https://github.com/gautamvarmadatla/mcpsafetywarden/actions/workflows/codeql.yml)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.gautamvarmadatla%2Fmcpsafetywarden)
[![Docker Pulls](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fhub.docker.com%2Fv2%2Frepositories%2Fgautamdatla1999%2Fmcpsafetywarden%2F&query=%24.pull_count&label=docker%20pulls&color=blue&cacheSeconds=300)](https://hub.docker.com/r/gautamdatla1999/mcpsafetywarden)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/gautamvarmadatla/mcpsafetywarden/badge)](https://scorecard.dev/viewer/?uri=github.com/gautamvarmadatla/mcpsafetywarden)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12730/badge)](https://www.bestpractices.dev/projects/12730)
[![GitHub Stars](https://img.shields.io/github/stars/gautamvarmadatla/mcpsafetywarden?style=social)](https://github.com/gautamvarmadatla/mcpsafetywarden)


## Contents

- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [MCP Integration](#mcp-integration)
- [CLI Reference](#cli-reference)
- [Auxiliary Integrations](#auxiliary-security-tool-integrations)
- [Development](#development)
- [Testing](#testing)
- [Further reading](#further-reading)

> [!IMPORTANT]
> MCP security is an active research area. Recent surveys catalog a lot of protocol-specific threat categories spanning tool poisoning, prompt injection, rug-pull attacks, supply chain compromise, credential exfiltration, and composition attacks across the full server lifecycle. See [Securing the MCP (OpenReview)](https://openreview.net/pdf?id=Aqn9Wdr2wN), [Landscape & Threats (arXiv)](https://arxiv.org/abs/2503.23278), [When MCP Servers Attack (arXiv)](https://arxiv.org/abs/2509.24272), and [MCP-38 Taxonomy (arXiv)](https://arxiv.org/abs/2603.18063).

## Overview

Use as a proxy to add safety gating to any MCP server, or point it at a server you don't own and run a full security audit without making a single tool call.

<p align="center">
  <img src="assets/two_operating_modes.jpg" alt="Two operating modes" width="800"/>
  <br/>
  <em>Fig 1. Two operating modes: proxy and audit</em>
</p>

**Behavioral profiling**: Effect class, retry safety, destructiveness. LLM-assisted (Anthropic, OpenAI, Gemini, Ollama) with rule-based fallback. Observed stats (latency p50/p95, failure rate, output size) updated after every proxied call.

**Security scanning**: mcpsafety+ five-stage pipeline (Recon, Planner, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (metadata analysis). Kali and Burp Suite integrations enrich the pipeline with real network data and HTTP-layer probes. Source code scanning from GitHub with entropy, AST, taint flow, and rug-pull detection.

<p align="center">
  <img width="1983" height="793" alt="3e457b83-6980-49fc-b812-350ab94f5633" src="https://github.com/user-attachments/assets/bb0c479b-32a9-464c-9b80-b7f295924266" />
  <br/>
  <em>Fig 2. mcpsafety+ five-stage pipeline, triggered when you run a full security audit on any MCP server</em>
</p>

**Safe execution**: Argument scanning (20+ attack categories, LLM second-pass). Two-layer output injection scanning. Risk gating with alternatives and per-tool policies. Drift detection on every call and standalone check.

<p align="center">
  <img width="1024" height="572" alt="fb949e62-5a3e-4a5c-be14-3523ef92295e" src="https://github.com/user-attachments/assets/5928e182-0f95-46aa-aa6e-88b4247ad137" />
  <br/>
  <em>Fig 3. Safe execution pipeline: the five checks every proxied tool call passes through</em>
</p>



**CLI**: 24 subcommands, interactive risk menu, `--json` flag on every command, `--yes` for CI.

**What it detects**

- **Prompt injection**: tool outputs trying to hijack the agent: role hijacking, jailbreaks, fake system prompts, instruction overrides. Detects 11 obfuscation techniques including Unicode lookalikes, zero-width characters, and base64-encoded payloads.
- **Malicious tool metadata**: descriptions containing injection strings, hardcoded secrets, suspicious download URLs, tool impersonation (shadowing), direct financial execution, system service modification, and untrusted external dependencies. Backed by 19 Snyk checks.
- **Argument injection**: 20+ attack categories checked on every tool call before the call is forwarded: SSRF to cloud metadata endpoints (AWS, GCP, Azure, Alibaba), path traversal, credential file access (.aws, .ssh, .kube, .env), command injection, SQL/NoSQL/LDAP/XPath injection, XXE, template injection (SSTI), CRLF, null byte, deserialization payloads (Java, Python pickle, PHP, .NET), Windows UNC/ADS attacks, and base64-obfuscated variants of all of the above.
- **Source code risks**: fetches the server's GitHub source and runs 6 analysis layers: entropy scanning for hardcoded secrets, AST taint flow tracking (parameter to dangerous sink), description-vs-implementation mismatch, Bandit and Semgrep SAST, and LLM cross-function reasoning. Supports Python and TypeScript/JavaScript.
- **Rug-pull and drift**: stores a SHA-256 hash of the server's source on first scan and alerts if it changes. Catches description swaps, schema changes, and tool removal live on every call via a per-call drift guard.
- **Behavior anomalies**: classifies every tool by effect class, destructiveness, and 7 risk tags: credential exposure, arbitrary execution, data exfiltration, filesystem access, lateral movement, privilege escalation, and prompt injection surface.
- **Composition attacks**: analyzes tool sets for chaining risks: IDOR chains, read-write pairs, auth flow exploitation, write-then-execute sequences, and data accumulation + exfiltration paths across multiple tools.
- **Network and host risks**: when Kali Linux MCP is registered: open ports, running services, OS fingerprint via nmap. When Burp Suite MCP is registered: HTTP-layer active probing and blind SSRF via out-of-band callbacks.
- **Credential exposure in outputs**: redacts secrets from tool responses before storage. Injection-flagged responses are quarantined and never returned to the calling agent - stored under a run ID for forensic review.
- **CVE research and Arxiv findings**: the mcpsafety+ Auditor stage cross-references discovered capabilities against known vulnerabilities and recent security research.


## Prerequisites

- Python 3.10 or later
- At least one wrapped MCP server to proxy (stdio, SSE, or streamable_http)
- **Recommended: an LLM API key** (Anthropic, OpenAI, or Gemini)

Without a key the wrapper operates in rule-based-only mode: lower confidence tool classification, regex-only injection scanning, no alternatives in the risk gate, no mcpsafety+ pipeline. For a fully local setup, run [Ollama](https://ollama.com), set `OLLAMA_MODEL`, and pass `--provider ollama` explicitly (Ollama is not auto-detected).

> [!NOTE]
> **stdio servers that require local setup** (`stdio` servers that need local configuration before starting - missing config files, credentials, data directories, or OS-specific dependencies) cannot be inspected by the wrapper - tool discovery will fail and 0 tools will be stored. You can still run a full source-code security scan without spawning the server by passing `--github-url` to `scan` / `onboard`, or the `github_url` parameter to `security_scan_server`. The mcpsafety+ pipeline will fetch and analyze the source directly from GitHub. `sse` and `streamable_http` servers are not affected.


## Installation

```bash
pip install mcpsafetywarden
```

With all optional extras:

```bash
pip install "mcpsafetywarden[all]"
```

Or specific extras:

```bash
pip install "mcpsafetywarden[anthropic,snyk]"
```

From source:

```bash
git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .
```

The SQLite database is created automatically on first run in the platform user data directory (`~/.local/share/mcpsafetywarden/` on Linux, `~/Library/Application Support/mcpsafetywarden/` on macOS, `%APPDATA%\mcpsafetywarden\` on Windows). Override with `MCP_DB_PATH`.

**Credential protection (automatic, no action required)**

Secret values passed to `register_server` or `onboard_server` (Bearer tokens, API keys in `headers` or `env`) are automatically detected and replaced with opaque `cref_` identifiers before anything touches the model context. The real credential is stored encrypted in the database and resolved silently at connection time. The model, conversation history, and logs only ever see `cref_<id>`.

**Optional: at-rest encryption for stored credentials**

```bash
pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

Set the printed key as `MCP_DB_ENCRYPTION_KEY` before starting the server. This encrypts both server credentials and `cref_` values at rest.


## Configuration

All configuration is via envir