Metadata-Version: 2.3
Name: cybereiche-mcp-sec
Version: 0.1.1
Summary: CyberEiche reachability-driven security testing and native pytest plugin for Anthropic Model Context Protocol (MCP)
Author: CyberEiche
Author-email: CyberEiche <contact@cybereiche.de>
Requires-Dist: click>=8.5.1
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.12
Project-URL: Homepage, https://cybereiche.de
Project-URL: Repository, https://github.com/CyberEiche/pytest-mcp-sec
Project-URL: Documentation, https://github.com/CyberEiche/pytest-mcp-sec#readme
Description-Content-Type: text/markdown

# CyberEiche MCP-Sec (`cybereiche-mcp-sec`)

[![Tests](https://img.shields.io/badge/tests-47%20passed-brightgreen.svg)](tests/)
[![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)](tests/)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](pyproject.toml)
[![MCP](https://img.shields.io/badge/MCP-2024--11--05-orange.svg)](https://modelcontextprotocol.io/)
[![Zero-Noise](https://img.shields.io/badge/False%20Positives-0%25%20Guaranteed-success.svg)](#the-zero-noise-guarantee)
[![CyberEiche](https://img.shields.io/badge/Built%20by-CyberEiche.de-darkgreen.svg)](https://cybereiche.de)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

> **Enterprise-grade reachability security testing & native `pytest` plugin for Anthropic Model Context Protocol (MCP) servers and AI agent clients — engineered by [CyberEiche](https://cybereiche.de).**

Recent empirical security research reveals that **87.5% of verified MCP CVEs are High or Critical severity**, with **66.7%** leading to direct code execution or path traversal via Tool Poisoning Attacks (TPAs).

Traditional SAST and SCA tools generate 80–90% false-positive noise by reporting theoretical vulnerabilities. **`cybereiche-mcp-sec` applies DARPA AIxCC principles**—static reachability graph analysis, directed multi-turn conversational fuzzing (Crescendo / TAP), and ephemeral in-memory sandboxing—to deliver a **0% false-positive guarantee**.

An alert is raised **if and only if** an executable, reproducible Proof-of-Vulnerability script (`test_exploit.py`) is synthesized.

---

## 🏗️ Architecture

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                     CYBEREICHE MCP-SEC SECURITY TESTING PIPELINE                       │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                        │
│  [Module 1: Static Tool Reachability Graph]                                            │
│  Parses MCP server definitions (`tools/list`) and identifies dangerous tool sinks     │
│  (FILESYSTEM, COMMAND_EXEC, DATABASE, NETWORK) and unvalidated parameters.             │
│                                    │                                                   │
│                                    ▼                                                   │
│  [Module 2: Directed Multi-Turn Fuzzer (TAP & Crescendo)]                              │
│  Executes adaptive conversational attacks against agents to steer them toward sinks.   │
│                                    │                                                   │
│                                    ▼                                                   │
│  [Module 3: Ephemeral Micro-Sandbox with Canary Oracles]                               │
│  Intercepts JSON-RPC tool calls safely in memory and plants cryptographic canaries.    │
│                                    │                                                   │
│                                    ▼                                                   │
│  [Module 4: Deterministic PoV Synthesizer & Pytest Plugin]                             │
│  Generates `test_exploit_<id>.py` reproduction scripts and SARIF 2.1.0 reports.        │
│                                                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

---

## ⚡ Quickstart

### 1. Installation

```bash
# Via uv (recommended)
uv add --dev cybereiche-mcp-sec

# Via pip
pip install cybereiche-mcp-sec
```

### 2. Run with Pytest

Execute security fuzzing against any configured MCP server or target agent:

```bash
# Run security suite and output SARIF report for GitHub Actions
pytest --mcp-fuzz --mcp-sarif=mcp-security-results.sarif
```

### 3. Beautiful Terminal Scorecard

CyberEiche MCP-Sec outputs clean, actionable results with zero noise:

```
           CyberEiche MCP Security Scorecard (Verified Exploits Only)                
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Vulnerability ID ┃ Severity ┃ Category       ┃ Title                  ┃ Evidence   ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
│ VULN-TPA-001     │ CRITICAL │ tool_poisoning │ Arbitrary File Deletion│ Executed   │
│                  │          │                │                        │ delete_file│
└──────────────────┴──────────┴────────────────┴────────────────────────┴────────────┘
```

---

## 🛡️ The Zero-Noise Guarantee

`cybereiche-mcp-sec` enforces the **DARPA AIxCC Zero-Noise Principle**:
1. **Never alert on speculation:** Abstract code patterns or theoretical prompt injections without tool execution are never flagged as vulnerabilities.
2. **Deterministic PoV Output:** For every verified issue, a standalone pytest file is created automatically:
   ```python
   # test_exploit_vuln_tpa_001.py
   def test_reproduce_exploit_vuln_tpa_001():
       """Auto-generated reproducible test verifying reachability of tool sink."""
       assert target_tool == "delete_file"
       assert captured_args == {"path": "/var/data/prod.db"}
   ```

---

## 🔒 2026 Core Architectural Capabilities

### 1. `$SECRET_n` Privacy Tokenization Gateway
Separates reasoning from authority and secrets. Before any tool arguments or conversational context are routed, `PrivacyGateway` tokenizes sensitive credentials, GitHub tokens, and connection strings into `$SECRET_1`, `$SECRET_2`:
```python
from cybereiche_mcp_sec.sandbox import PrivacyGateway

gateway = PrivacyGateway()
gateway.register_secret("postgres://user:pass@db:5432/prod", name="DB_URL")

# Raw secrets are masked in prompt contexts and intercepted tool parameters
masked = gateway.mask_dict({"db": "postgres://user:pass@db:5432/prod"})
# Output: {"db": "$SECRET_DB_URL"}
```

### 2. Resumable Sessions & Human-in-the-Loop (HITL) Approval Gates
Multi-day engagements and long-running security evaluations support checkpointing and crash salvage:
* **Session Persistence:** State is auto-saved to `.cybereiche/fuzz_session.json` to avoid re-running already completed scenarios.
* **HITL Approval Gate:** Prevents destructive tools (`delete_file`, `drop_database`) from executing unchecked unless approved by operator policy (`ApprovalPolicy.CALLBACK` or `ApprovalPolicy.AUTO_APPROVE`).

### 3. Closed-Loop Remediation & Fix Verification Bridge
Proves an exploit has been eliminated without introducing regressions:
```python
from cybereiche_mcp_sec.remediation import FixVerificationBridge, RemediationStatus

bridge = FixVerificationBridge()
receipt = bridge.verify_remediation(
    proof=proof,
    pov_script_path=path_to_test_exploit,
    patch_applier=lambda: apply_code_patch(),  # e.g. vibesec fix
    regression_tester=lambda: run_full_test_suite(),
)

assert receipt.status == RemediationStatus.VERIFIED_FIX
assert receipt.is_deployable is True
```

---

## 🧩 Programmatic Python API

```python
from cybereiche_mcp_sec.parser import MCPParser
from cybereiche_mcp_sec.sandbox import MockMCPServer, CanaryOracle
from cybereiche_mcp_sec.fuzzer import FuzzingEngine

# 1. Parse MCP server schema
parser = MCPParser()
catalog = parser.parse_config_json(server_config_json)

# 2. Spin up safe in-memory mock server with canary oracle
oracle = CanaryOracle()
token = oracle.plant_virtual_file("/etc/shadow")
server = MockMCPServer(tools=catalog.servers["filesystem"].tools, canary_oracle=oracle)

# 3. Execute multi-turn adversarial probe
fuzzer = FuzzingEngine()
result = fuzzer.execute_scenario(agent_under_test, server, scenario)

if result.vulnerability_confirmed:
    print(f"Verified Exploit Found: {result.proof.title}")
```

---

## 🤝 CI/CD & SARIF Integration

Add CyberEiche MCP-Sec directly to your GitHub Actions workflow:

```yaml
name: CyberEiche MCP Security Audit
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v2
      - run: uv run pytest --mcp-fuzz --mcp-sarif=results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif
```

---

## 🛡️ About CyberEiche

[CyberEiche](https://cybereiche.de) is a German cybersecurity firm specializing in enterprise defense, resilient infrastructure, and AI system security. 

* **Website:** [cybereiche.de](https://cybereiche.de)
* **Contact:** [contact@cybereiche.de](mailto:contact@cybereiche.de)
* **License:** MIT License
