Metadata-Version: 2.3
Name: cybereiche-mcp-sec
Version: 0.1.2
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 🛡️
### *Deterministic MCP Vulnerability Verification, Agent Fuzzing & Zero-Noise Pytest Gate*

[![PyPI version](https://img.shields.io/pypi/v/cybereiche-mcp-sec.svg)](https://pypi.org/project/cybereiche-mcp-sec/)
![Tests](https://img.shields.io/badge/tests-52%20passed-brightgreen.svg)
![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)
![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)
![MCP Spec](https://img.shields.io/badge/MCP-2024--11--05-orange.svg)
![False Positives](https://img.shields.io/badge/False%20Positives-0%25%20Guaranteed-success.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)

---

## ⚡ TL;DR — Quick Command Cheat Sheet (For the Busy Developer)

```bash
# 📦 1. Install CyberEiche MCP-Sec
pip install cybereiche-mcp-sec
# Or via uv
uv add --dev cybereiche-mcp-sec

# 🔍 2. Run Directed Fuzzing via Native Pytest
pytest --mcp-fuzz

# 🎯 3. Target a Specific MCP Server Config (Desktop / Claude / Stdio)
pytest --mcp-fuzz --mcp-target path/to/claude_desktop_config.json

# 📋 4. Export OASIS SARIF 2.1.0 Report (for GitHub Security tab & IDEs)
pytest --mcp-fuzz --mcp-sarif results.sarif

# 🔄 5. Resumable Session with Crash Salvage (Multi-day or long-running scans)
pytest --mcp-fuzz --mcp-session .cybereiche/fuzz_session.json

# 🛡️ 6. Enforce Human-in-the-Loop (HITL) Confirmation for Destructive Sinks
pytest --mcp-fuzz --mcp-hitl

# 🛠️ 7. Verify an Automated Fix Neutralizes the PoV (Closed-Loop Remediation)
pytest --mcp-verify-fix fix.patch
```

---

## 💥 The Real Problem We Solve

In late-2026, **87.5% of verified MCP CVEs are High or Critical severity**, with over **66%** leading to direct Arbitrary Code Execution (ACE) or Path Traversal via Tool Poisoning Attacks (TPAs).

Traditional security scanners give agent developers two bad choices:
1. **Noisy SAST / LLM Scanners**: 80–90% false-positive noise from theoretical prompt injections and hallucinations that never actually compromise a tool.
2. **Unchecked Black-Box Attackers**: Burn thousands of dollars in LLM tokens guessing blind, leak API credentials in prompt contexts, and stop at a 50-page PDF without reproducible proof.

### The CyberEiche Difference:
* **0% False-Positive Guarantee (Machine Oracle)**: Enforces DARPA AIxCC principles. A vulnerability is alerted **if and only if** an executable, reproducible `test_exploit_<id>.py` script is synthesized and verified.
* **Local Privacy Gateway (`$SECRET_n` Tokenization)**: Credentials, connection strings, and tokens are intercepted and tokenized before reaching LLM contexts or execution logs.
* **Closed-Loop Fix Verification**: Connects verified findings directly to automated fixers (such as [`cybereiche-vibesec fix`](https://pypi.org/project/cybereiche-vibesec/)) and confirms that the exploit is neutralized with **zero test regressions**.

---

## 🏗️ Architecture & Verification Lifecycle

```
[1. MCP CATALOG PARSER]  ──► Deep JSON Schema & Desktop Config Discovery
                               │ *Maps dangerous sinks: FILESYSTEM, EXEC, DB, NETWORK*
                               ▼
[2. PRIVACY GATEWAY]     ──► Tokenizes credentials ($SECRET_n) & enforces scope boundaries
                               │ *Zero credential leakage to model prompts or logs*
                               ▼
[3. MULTI-TURN FUZZER]   ──► Adaptive conversational attacks (Crescendo & TAP)
                               │ *Guided multi-step steering toward dangerous sinks*
                               ▼
[4. MICRO-SANDBOX & ORACLE]► Ephemeral JSON-RPC mock server with cryptographic canaries
                               │ *Multi-encoding exfiltration detection (Raw, B64, URL, Hex)*
                               ▼
[5. MACHINE ORACLE POV]  ──► Auto-generates reproducible test_exploit_<id>.py & SARIF 2.1.0
                               │ *0% noise: Drops unverified alerts; saves session state*
                               ▼
[6. CLOSED-LOOP FIX]     ──► Re-runs PoV against patches to guarantee verified remediation
```

---

## 📋 Complete CLI & Pytest Options Reference

| Flag | Argument | Description |
| :--- | :--- | :--- |
| `--mcp-fuzz` | Flag | Activates CyberEiche MCP fuzzing engine within pytest. |
| `--mcp-target` | `<path>` | Path to MCP server catalog or `claude_desktop_config.json`. |
| `--mcp-sarif` | `<path>` | Serializes verified vulnerabilities to standard SARIF 2.1.0 JSON. |
| `--mcp-session` | `<path>` | Checkpoints state atomically to allow resuming interrupted fuzzing runs. |
| `--mcp-hitl` | Flag | Prompts operator confirmation before dangerous sinks execute. |
| `--mcp-verify-fix`| `<path>` | Validates that a candidate patch neutralizes the synthesized PoV. |

---

## 🛡️ The Zero-Noise Guarantee & PoV Synthesis

CyberEiche MCP-Sec outputs clear, actionable scorecards in the terminal:

```
           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│
└──────────────────┴──────────┴────────────────┴────────────────────────┴────────────┘
```

For every confirmed 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 Enterprise Capabilities

### 1. `$SECRET_n` Privacy Tokenization Gateway
Separates reasoning from authority. Credentials never reach the LLM or logs:

```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. Atomic Session Checkpointing & HITL Approval
Multi-hour runs are saved atomically with crash salvage:

```python
from cybereiche_mcp_sec.fuzzer import FuzzingSessionManager, HITLApprovalGate

manager = FuzzingSessionManager(session_path=".cybereiche/session.json")
session = manager.load_or_create()

gate = HITLApprovalGate(on_approval_required=lambda tool, args: True)
assert gate.request_approval("delete_table", {"table": "users"}) is True
```

### 3. Closed-Loop Remediation Bridge
Verifies that code fixes neutralize the exploit without 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_git_patch("fix.patch"),
    regression_tester=lambda: run_full_test_suite(),
)

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

---

## 🏢 GitHub Actions CI/CD Integration

Embed continuous MCP security verification into your pipeline:

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

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

---

## 🌐 The CyberEiche Security Ecosystem

`cybereiche-mcp-sec` is part of the CyberEiche product suite:

* **[cybereiche-vibesec](https://pypi.org/project/cybereiche-vibesec/)**: Autonomous AppSec, PostgreSQL RLS multi-tenant audit, and automated code fixes (`vibesec fix`).
* **[cybereiche-mcp-sec](https://pypi.org/project/cybereiche-mcp-sec/)**: Deterministic MCP security verification, agent reachability fuzzing, and PoV generation.

---

## 🛡️ About CyberEiche

**[CyberEiche](https://cybereiche.de)** is a German cybersecurity firm based in Düsseldorf, specializing in enterprise defense, sovereign AI system security, and resilient cloud architectures.

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