MCP-Bastion

# MCP-Bastion

<!-- mcp-name: io.github.vaquarkhan/mcp-bastion -->

<p align="center">
  <img
    src="images/mcp-bastian.png"
    alt="MCP-Bastion  -  Fortifying the Model Context Protocol"
    width="720"
    style="max-width:100%; height:auto;"
  />
</p>

[![PyPI version](https://img.shields.io/pypi/v/mcp-bastion-python.svg?label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/mcp-bastion-python/3.3.0/)
[![PePy all-time downloads (mcp-bastion-python)](https://img.shields.io/pepy/dt/mcp-bastion-python?label=PePy%20all-time%20downloads)](https://pepy.tech/projects/mcp-bastion-python)
[![Python](https://img.shields.io/pypi/pyversions/mcp-bastion-python)](https://pypi.org/project/mcp-bastion-python/)
[![CI](https://img.shields.io/github/actions/workflow/status/vaquarkhan/MCP-Bastion/ci.yml?branch=main&label=CI)](https://github.com/vaquarkhan/MCP-Bastion/actions/workflows/ci.yml)
[![Docker proxy (GHCR)](https://img.shields.io/badge/GHCR-mcp--bastion--proxy-2496ED?logo=docker)](https://github.com/vaquarkhan/MCP-Bastion/pkgs/container/mcp-bastion-proxy)
[![Docker dashboard (GHCR)](https://img.shields.io/badge/GHCR-mcp--bastion--dashboard-2496ED?logo=docker)](https://github.com/vaquarkhan/MCP-Bastion/pkgs/container/mcp-bastion-dashboard)
[![License: Source Available](https://img.shields.io/badge/license-Source%20Available-orange.svg)](LICENSE)
[![Website](https://img.shields.io/badge/website-vaquarkhan.github.io/MCP--Bastion-blue?logo=github)](https://vaquarkhan.github.io/MCP-Bastion/)

**Current release: [3.3.0](https://pypi.org/project/mcp-bastion-python/3.3.0/)** · Docker `v3.3.0` · 18 PyPI packages · [CHANGELOG](CHANGELOG.md)

**The Zero-Trust control plane for MCP agents.** Your agent can call databases, APIs, and shell tools. One bad prompt can leak PII; one runaway loop can burn your API budget in minutes; three agents on one server with no identity boundary is a confused-deputy incident waiting to happen. MCP-Bastion wraps your MCP server with **local** guardrails: **agent IAM**, supply-chain checksums, injection blocking, PII redaction, and **denial-of-wallet caps**, under **5ms overhead**, with no third-party safety API.

**Guiding rule:** Stay a **zero-infra, drop-in library**  -  the guardrail brain that composes with any gateway, not a gateway itself. Strategy: [docs/ZERO_INFRA_STRATEGY.md](docs/ZERO_INFRA_STRATEGY.md).

<p align="center">
  <img
    src="images/mcp-bastion-scan-test-enforce.png"
    alt="MCP-Bastion: SCAN → TEST → ENFORCE - No other tool has all three"
    width="960"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>

### Scan → Test → Enforce (no other tool has all three)

| Phase | What | Command |
|-------|------|---------|
| **Scan** | Static tool-definition checks before deploy (injection, secrets, homoglyphs, fingerprint drift, schema preconditions) | `mcp-bastion scan tools.json` |
| **Audit** | Local MCP client-config risk report (over-broad tools, standing credentials, filesystem servers) | `mcp-bastion audit` |
| **Test** | Integrated red-team harness against your `bastion.yaml` policy | `mcp-bastion redteam` |
| **Enforce** | Runtime middleware on every MCP method | `secure_fastmcp(mcp)` or `bastion.yaml` |

**`scan` vs `audit` - different inputs, different questions**

| | **`mcp-bastion scan`** | **`mcp-bastion audit`** |
|---|------------------------|-------------------------|
| **Looks at** | A **tool catalog** (`tools.json` / `tools/list` export) | **MCP client configs** on disk (`mcp.json`, Claude Desktop config, etc.) |
| **Asks** | “Is this **tool metadata** poisoned or drifted?” | “What can agents **already reach** on this machine?” |
| **Finds** | Injection in descriptions, secrets in schemas, homoglyphs, fingerprint drift, weak/unbounded inputSchema shapes | Over-broad tool grants (`*`), standing credentials in `env`, filesystem-server hints |
| **When** | Before you ship or attach a server’s tools (CI / pre-deploy) | Before you tighten policy on a laptop or workspace (local hygiene) |

They complement each other: **audit** the host surface, then **scan** the tools you attach. Neither replaces runtime **enforce**.

`mcp-bastion scan` also accepts `--skills DIR` for offline agent skill-file checks. Dependency CVEs: `mcp-bastion osv-refresh` then `mcp-bastion osv-scan` (local DB default; `--online` opt-in, fail-open).

```bash
# 1. Scan a tools/list export (or hand-authored catalog) - client-side, no cloud
mcp-bastion scan examples/fixtures/tools-poisoned.json
mcp-bastion fingerprint tools.json -o baseline.json
mcp-bastion scan tools.json --baseline baseline.json --format json -o report.json
mcp-bastion scan --skills ./skills/

# 1b. Audit local MCP client configs (what agents can already reach)
mcp-bastion audit --root .
mcp-bastion audit --format json -o risk-audit.json --fail-on none

# 2. Test policy effectiveness
mcp-bastion redteam --config bastion.yaml

# 3. Enforce at runtime (filesystem path guards when agents can read local files)
#    merge examples/bastion-filesystem-guards.yaml into bastion.yaml
mcp-bastion validate --config bastion.yaml
```

<p align="center">
  <img
    src="images/mcp-bastion-scan-cli.png"
    alt="mcp-bastion scan CLI - flags injection, secrets, homoglyphs, and fingerprint drift with letter grade A–F"
    width="920"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>
<p align="center"><sub><code>mcp-bastion scan</code> - client-side static scanner; no cloud, no ML download</sub></p>

<p align="center">
  <img
    src="images/mcp-bastion-audit-cli.png"
    alt="mcp-bastion audit CLI - local MCP risk audit of client configs, over-broad tools, and standing credentials"
    width="920"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>
<p align="center"><sub><code>mcp-bastion audit</code> - map the local MCP surface before you enforce; no network, no vault</sub></p>

<p align="center">
  <img
    src="images/mcp-bastion-scan-suite.png"
    alt="MCP-Bastion client-side scan suite - schema preconditions, skill files, OSV dependency CVE lookup"
    width="960"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>
<p align="center"><sub>Schema · Skills · OSV - offline by default; no login server; no phone-home</sub></p>

<p align="center">
  <a href="images/mcp-bastion-dashboard-tour.gif" title="MCP-Bastion dashboard feature tour (GIF)">
    <img
      src="images/mcp-bastion-dashboard-tour.gif"
      alt="MCP-Bastion dashboard tour: posture, prevalidation, OWASP, attack matrix, forensics, FinOps actual vs would-have-been"
      width="960"
      style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b; box-shadow:0 8px 32px rgba(15,23,42,0.35);"
    />
  </a>
</p>
<p align="center"><sub>Feature tour</sub></p>
<p align="center">
  <a href="images/deshboard-walkthrow.gif" title="MCP-Bastion dashboard walkthrough (GIF)">
    <img
      src="images/deshboard-walkthrow.gif"
      alt="MCP-Bastion dashboard walkthrough GIF"
      width="960"
      style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b; box-shadow:0 8px 32px rgba(15,23,42,0.35);"
    />
  </a>
</p>
<p align="center"><sub>Dashboard walkthrough</sub></p>
<p align="center">
  <img
    src="images/mcp-bastion-dashboard.png"
    alt="MCP-Bastion dashboard collage - security posture, OWASP coverage, attack matrix, and runtime KPIs"
    width="960"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>
<p align="center"><strong>Live security posture + runtime dashboard</strong> - local-only, zero infra. <code>mcp-bastion dashboard --demo</code> · <a href="dashboard/README.md">Dashboard docs</a> · <a href="https://vimeo.com/1186084574">Older Vimeo walkthrough</a></p>

<p align="center">
  <img
    src="images/mcp-bastion-mcp-surface-scale.png"
    alt="MCP-Bastion: full MCP method coverage and Redis shared state for multi-replica deployments"
    width="960"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>

<p align="center">
  <img
    src="images/mcp-bastion-hybrid-transport.svg"
    alt="MCP-Bastion hybrid stateful and stateless MCP transport with discovery, Redis-backed FinOps keys, and agent stability"
    width="960"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>
<p align="center">
  <img
    src="images/mcp-bastion-hybrid-dual-path.svg"
    alt="MCP-Bastion 3.2 dual-path: legacy stateful sessions and SEP-2575-ready stateless state handles on one proxy"
    width="960"
    style="max-width:100%; height:auto; border-radius:12px; border:1px solid #1e293b;"
  />
</p>
<p align="center"><strong>Hybrid stateful / stateless MCP (3.2.0)</strong> - opt-in <code>mcp_transport</code> for SEP-2575 readiness without breaking legacy sessions. <a href="docs/HYBRID_MCP_TRANSPORT.md">Architecture</a> · <a href="docs/HYBRID_TRANSPORT_TUTORIAL.md">Tutorial</a></p>

## Why MCP-Bastion? (Solving the 2026 MCP Security Crisis)

As noted in the NSA's recent Cybersecurity Information Sheet on MCP security and the OWASP MCP Top 10, traditional AppSec tools cannot secure agentic workflows. The gap is **runtime governance** and the **confused deputy problem**: multiple AI agents sharing one MCP server with no native identity boundary. Public registry typosquatting and unverified servers have made supply-chain verification a board-level concern.

MCP-Bastion acts as the **Zero-Trust Control Plane** for your agents, addressing the hardest production problems:

1. **The Confused Deputy (Agent IAM):** Identity-aware routing binds API tokens to **Agent Identities** and enforces strict per-tool RBAC. Your customer-support bot can call `search_docs`, not `delete_user`.
2. **Supply chain & typosquatting defense:** Cryptographic SHA-256 man