redteam-mcp 0.2.0__tar.gz

redteam_mcp-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+reports/*.html
+!examples/sample-report.html
+.DS_Store
+docs/research-synthesis.md
+docs/playbook-gaps.md
+docs/agent-architecture-draft.md
+docs/research-*.md
+docs/cto-analysis.md
+docs/documentation-audit.md
+docs/competitive-analysis.md
+docs/overnight-notes.md
+docs/playbook-gaps.md
+docs/agent-architecture-draft.md
+__pycache__/
+*.pyc
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/

redteam_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m0rvayne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

redteam_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: redteam-mcp
+Version: 0.2.0
+Summary: MCP server security auditor — deterministic engine + AI-native behavioral analysis
+Project-URL: Homepage, https://github.com/m0rvayne/mcp-redteam
+Project-URL: Repository, https://github.com/m0rvayne/mcp-redteam
+Author-email: m0rvayne <m0rvayne@proton.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,mcp,pentest,red-team,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == 'llm'
+Requires-Dist: instructor>=1.0; extra == 'llm'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/logo.svg" alt="mcp-redteam" width="700">
+
+**It doesn't tell you where your walls are thin. It walks through them.**
+
+[![Tests](https://github.com/m0rvayne/mcp-redteam/actions/workflows/test.yml/badge.svg)](https://github.com/m0rvayne/mcp-redteam/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![OWASP MCP Top 10](https://img.shields.io/badge/OWASP-MCP%20Top%2010-orange)](https://owasp.org/www-project-mcp-top-10/)
+[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-plugin-7b61ff)](https://claude.ai/code)
+
+</div>
+
+---
+
+MCP server security auditor. Two modes of operation:
+
+- **Claude Code plugin** — AI-native deep audit. Reads source code semantically, probes tools, detects behavioral mismatches, maps cross-server attack chains. Interactive HTML report.
+- **Standalone CLI** — deterministic scan. 14 Semgrep rules, config health checks, SARIF output. Works in CI/CD without Claude.
+
+## What works today
+
+| Feature | Status | How |
+|---------|--------|-----|
+| Config health scanner | Working | Dead servers, scope conflicts, credential exposure, supply chain, CVE checks |
+| Semgrep code analysis | Working | 14 rules (Python + JS/TS): injection, traversal, SSRF, eval, secrets, stdout |
+| SARIF output | Working | GitHub Security tab integration |
+| JSON output | Working | Machine-readable for CI/CD |
+| Terminal output | Working | Rich colored tables with risk scores |
+| CI exit codes | Working | `--fail-on critical` returns exit 1 |
+| LLM behavioral analysis | Working | Anthropic SDK, behavioral mismatch detection (optional) |
+| Audit history | Working | JSONL log, cross-run comparison (new/confirmed/fixed) |
+| Self-security audit | Working | 10 vulnerabilities found and fixed in own code |
+| Claude Code plugin | Working | AI-driven deep audit with HTML report |
+| 75+ tests | Passing | Unit, security, stress, edge cases, Hypothesis fuzzing |
+
+## What doesn't work yet
+
+- Cross-server chain detection in CLI (exists in Claude Code plugin only)
+- Auto-fix in CLI (exists in Claude Code plugin only)
+- HTML report generation in CLI
+- MCPTox benchmark validation
+- Community rule contributions
+
+## Install
+
+**Claude Code plugin** (deep AI-native audit):
+```bash
+claude plugin marketplace add m0rvayne/mcp-redteam
+claude plugin install mcp-redteam
+/mcp-redteam
+```
+
+**Standalone CLI** (deterministic, CI/CD ready):
+```bash
+pip install mcp-redteam
+mcp-redteam scan ./your-mcp-server --no-llm
+```
+
+Requires Python 3.10+. Semgrep installed separately for code analysis: `pip install semgrep`.
+
+## What it checks
+
+### Config Health (deterministic)
+
+Dead/disconnected servers, scope conflicts (same server in multiple scopes), credentials in git-tracked config files (CVE-2025-59536), unpinned npx/uvx packages (supply chain), enableAllProjectMcpServers bypass (CVE-2026-21852), orphaned MCP processes.
+
+### Code Security (Semgrep, 14 rules)
+
+| Rule | What it detects | Languages |
+|------|----------------|-----------|
+| Shell injection | subprocess + shell=True with user input | Python |
+| Path traversal | open()/Path() without realpath check | Python, JS/TS |
+| SSRF | HTTP requests with user-controlled URL | Python, JS/TS |
+| Eval injection | eval()/exec()/new Function() with user input | Python, JS/TS |
+| Hardcoded secrets | API keys, tokens, passwords in source | Python, JS/TS |
+| Stdout pollution | print()/console.log() in MCP handlers | Python, JS/TS |
+| Missing error handling | Tool functions without try/except | Python |
+| Credential in response | API keys/tokens in tool return values | Python |
+
+Based on 48+ CVEs, OWASP MCP Top 10, and research from Invariant Labs, Trail of Bits, Palo Alto Unit 42, OX Security, and Snyk.
+
+### LLM Behavioral Analysis (optional, requires API key)
+
+- **Behavioral mismatch**: tool description claims X, code does Y
+- **Hidden operations**: undeclared network requests, file writes, subprocess calls
+- **Credential mishandling**: secrets logged, leaked in errors, stored insecurely
+
+## How it compares
+
+| | mcp-scan (Snyk) | Cisco MCP Scanner | **mcp-redteam** |
+|---|---|---|---|
+| Approach | Static description scan | YARA + LLM-as-judge | **Semgrep taint + LLM behavioral** |
+| Reads source code | No | Python only | **Yes — Python + JS/TS** |
+| Config validation | No | Config discovery | **Yes — 6 checks, CVE detection** |
+| Behavioral mismatch | No | No | **Yes (LLM layer)** |
+| SARIF output | No | No | **Yes** |
+| CI exit codes | Yes | No | **Yes** |
+| Self-tested | Unknown | Unknown | **75+ tests, self-security audit** |
+| Cloud dependency | Snyk API required | Cisco API (optional) | **No — fully local** |
+
+### Why not just use mcp-scan?
+
+mcp-scan reads what a server **says about itself** — tool descriptions. mcp-redteam checks what a server **actually does** — source code analysis + behavioral analysis.
+
+A server with clean descriptions but leaky code: mcp-scan passes it. We catch it.
+
+Real findings mcp-scan cannot detect (they live in code, not descriptions):
+- Trello API keys in `.env` committed to git
+- Instagram session cookies stored in plaintext
+- AppleScript injection via unescaped clipboard input
+- Google OAuth tokens with permissions `644`
+
+## Audit History
+
+Each audit saves a compact JSONL log to `~/Desktop/redteam-results/`. On the next run, mcp-redteam reads previous results and compares:
+
+- **confirmed** — found again, higher confidence
+- **new** — first time seeing this
+- **fixed** — was in previous audit, now gone
+
+This turns LLM non-determinism into an advantage: each run is a new perspective, the intersection is ground truth.
+
+## Architecture
+
+```
+ /mcp-redteam
+      |
+ +-----------------+
+ | Phase 0: Config |
+ +-----------------+
+      |
+ +-----------+
+ | Discovery |
+ +-----------+
+      |
+      |   1 server = 1 agent
+      |
+ +----------+ +----------+ +----------+ +----------+
+ | Agent-01 | | Agent-02 | | Agent-03 | | Agent-N  |
+ | youtube  | | trello   | | instagram| | server-N |
+ | health   | | health   | | health   | | health   |
+ | arch     | | arch     | | arch     | | arch     |
+ | complete | | complete | | complete | | complete |
+ | security | | security | | security | | security |
+ +----+-----+ +----+-----+ +----+-----+ +----+-----+
+      |            |            |            |
+      +------+-----+-----+------+
+             |
+ +-------------------------+
+ | Chain analysis + report |
+ +-------------------------+
+             |
+    +----------------+
+    | HTML + Fix     |
+    +----------------+
+```
+
+## Tests
+
+75+ tests across 6 test files:
+
+- **test_semgrep.py** — each vulnerable fixture detected, each benign fixture clean
+- **test_self_security.py** — 21 tests: our own code audited for vulnerabilities
+- **test_stress.py** — 1000/10000 findings, concurrent scans, unicode
+- **test_fuzzing.py** — Hypothesis property-based: any input, no crash
+- **test_edge_cases.py** — corrupt JSON, missing files, null bytes, timeouts
+- **test_models.py** + **test_formatters.py** — unit tests for core logic
+
+## Current Limitations
+
+- Plugin requires Claude Code with connected MCP servers
+- CLI requires semgrep for code analysis (graceful skip if not installed)
+- LLM analysis requires ANTHROPIC_API_KEY
+- Destructive tests intentionally skipped — read-only probing only
+- Source code analysis works for local servers; pip/npm packages may have limited access
+- Plugin report quality scales with model capability (Opus > Sonnet > Haiku)
+- False positive rate not yet measured on production MCP servers
+
+### Known False Positive Patterns
+
+- SSRF rule triggers on `httpx.get()` with URL built from config, not user input
+- Path traversal rule triggers on `open()` where path is validated but validation isn't recognized as sanitizer
+- Stdout pollution flags `print()` in `__main__` block (safe, not in MCP handler)
+
+## Docs
+
+The `docs/` folder is useful independently:
+
+- **[attack-playbook.md](docs/attack-playbook.md)** — 18 attack categories, 48+ CVEs, payloads and detection methods
+- **[best-practices.md](docs/best-practices.md)** — MCP server security checklist
+- **[reference-server.md](docs/reference-server.md)** — secure server templates (Python + Node.js)
+
+## References
+
+- [OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/)
+- [Invariant Labs — Tool Poisoning Attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)
+- [Trail of Bits — MCP Security Layer](https://blog.trailofbits.com/2025/07/28/we-built-the-security-layer-mcp-always-needed/)
+- [Palo Alto Unit 42 — MCP Attack Vectors](https://unit42.paloaltonetworks.com/model-context-protocol-attack-vectors/)
+- [OX Security — STDIO Design Flaw](https://www.ox.security/blog/the-mother-of-all-ai-supply-chains-critical-systemic-vulnerability-at-the-core-of-the-mcp/)
+- [NSA — MCP Security Guidance](https://www.nsa.gov/Portals/75/documents/Cybersecurity/CSI_MCP_SECURITY.pdf)
+- [Vulnerable MCP Project](https://vulnerablemcp.info/)
+
+## License
+
+[MIT](LICENSE)

redteam_mcp-0.2.0/README.md

@@ -0,0 +1,206 @@
+<div align="center">
+
+<img src="assets/logo.svg" alt="mcp-redteam" width="700">
+
+**It doesn't tell you where your walls are thin. It walks through them.**
+
+[![Tests](https://github.com/m0rvayne/mcp-redteam/actions/workflows/test.yml/badge.svg)](https://github.com/m0rvayne/mcp-redteam/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![OWASP MCP Top 10](https://img.shields.io/badge/OWASP-MCP%20Top%2010-orange)](https://owasp.org/www-project-mcp-top-10/)
+[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-plugin-7b61ff)](https://claude.ai/code)
+
+</div>
+
+---
+
+MCP server security auditor. Two modes of operation:
+
+- **Claude Code plugin** — AI-native deep audit. Reads source code semantically, probes tools, detects behavioral mismatches, maps cross-server attack chains. Interactive HTML report.
+- **Standalone CLI** — deterministic scan. 14 Semgrep rules, config health checks, SARIF output. Works in CI/CD without Claude.
+
+## What works today
+
+| Feature | Status | How |
+|---------|--------|-----|
+| Config health scanner | Working | Dead servers, scope conflicts, credential exposure, supply chain, CVE checks |
+| Semgrep code analysis | Working | 14 rules (Python + JS/TS): injection, traversal, SSRF, eval, secrets, stdout |
+| SARIF output | Working | GitHub Security tab integration |
+| JSON output | Working | Machine-readable for CI/CD |
+| Terminal output | Working | Rich colored tables with risk scores |
+| CI exit codes | Working | `--fail-on critical` returns exit 1 |
+| LLM behavioral analysis | Working | Anthropic SDK, behavioral mismatch detection (optional) |
+| Audit history | Working | JSONL log, cross-run comparison (new/confirmed/fixed) |
+| Self-security audit | Working | 10 vulnerabilities found and fixed in own code |
+| Claude Code plugin | Working | AI-driven deep audit with HTML report |
+| 75+ tests | Passing | Unit, security, stress, edge cases, Hypothesis fuzzing |
+
+## What doesn't work yet
+
+- Cross-server chain detection in CLI (exists in Claude Code plugin only)
+- Auto-fix in CLI (exists in Claude Code plugin only)
+- HTML report generation in CLI
+- MCPTox benchmark validation
+- Community rule contributions
+
+## Install
+
+**Claude Code plugin** (deep AI-native audit):
+```bash
+claude plugin marketplace add m0rvayne/mcp-redteam
+claude plugin install mcp-redteam
+/mcp-redteam
+```
+
+**Standalone CLI** (deterministic, CI/CD ready):
+```bash
+pip install mcp-redteam
+mcp-redteam scan ./your-mcp-server --no-llm
+```
+
+Requires Python 3.10+. Semgrep installed separately for code analysis: `pip install semgrep`.
+
+## What it checks
+
+### Config Health (deterministic)
+
+Dead/disconnected servers, scope conflicts (same server in multiple scopes), credentials in git-tracked config files (CVE-2025-59536), unpinned npx/uvx packages (supply chain), enableAllProjectMcpServers bypass (CVE-2026-21852), orphaned MCP processes.
+
+### Code Security (Semgrep, 14 rules)
+
+| Rule | What it detects | Languages |
+|------|----------------|-----------|
+| Shell injection | subprocess + shell=True with user input | Python |
+| Path traversal | open()/Path() without realpath check | Python, JS/TS |
+| SSRF | HTTP requests with user-controlled URL | Python, JS/TS |
+| Eval injection | eval()/exec()/new Function() with user input | Python, JS/TS |
+| Hardcoded secrets | API keys, tokens, passwords in source | Python, JS/TS |
+| Stdout pollution | print()/console.log() in MCP handlers | Python, JS/TS |
+| Missing error handling | Tool functions without try/except | Python |
+| Credential in response | API keys/tokens in tool return values | Python |
+
+Based on 48+ CVEs, OWASP MCP Top 10, and research from Invariant Labs, Trail of Bits, Palo Alto Unit 42, OX Security, and Snyk.
+
+### LLM Behavioral Analysis (optional, requires API key)
+
+- **Behavioral mismatch**: tool description claims X, code does Y
+- **Hidden operations**: undeclared network requests, file writes, subprocess calls
+- **Credential mishandling**: secrets logged, leaked in errors, stored insecurely
+
+## How it compares
+
+| | mcp-scan (Snyk) | Cisco MCP Scanner | **mcp-redteam** |
+|---|---|---|---|
+| Approach | Static description scan | YARA + LLM-as-judge | **Semgrep taint + LLM behavioral** |
+| Reads source code | No | Python only | **Yes — Python + JS/TS** |
+| Config validation | No | Config discovery | **Yes — 6 checks, CVE detection** |
+| Behavioral mismatch | No | No | **Yes (LLM layer)** |
+| SARIF output | No | No | **Yes** |
+| CI exit codes | Yes | No | **Yes** |
+| Self-tested | Unknown | Unknown | **75+ tests, self-security audit** |
+| Cloud dependency | Snyk API required | Cisco API (optional) | **No — fully local** |
+
+### Why not just use mcp-scan?
+
+mcp-scan reads what a server **says about itself** — tool descriptions. mcp-redteam checks what a server **actually does** — source code analysis + behavioral analysis.
+
+A server with clean descriptions but leaky code: mcp-scan passes it. We catch it.
+
+Real findings mcp-scan cannot detect (they live in code, not descriptions):
+- Trello API keys in `.env` committed to git
+- Instagram session cookies stored in plaintext
+- AppleScript injection via unescaped clipboard input
+- Google OAuth tokens with permissions `644`
+
+## Audit History
+
+Each audit saves a compact JSONL log to `~/Desktop/redteam-results/`. On the next run, mcp-redteam reads previous results and compares:
+
+- **confirmed** — found again, higher confidence
+- **new** — first time seeing this
+- **fixed** — was in previous audit, now gone
+
+This turns LLM non-determinism into an advantage: each run is a new perspective, the intersection is ground truth.
+
+## Architecture
+
+```
+ /mcp-redteam
+      |
+ +-----------------+
+ | Phase 0: Config |
+ +-----------------+
+      |
+ +-----------+
+ | Discovery |
+ +-----------+
+      |
+      |   1 server = 1 agent
+      |
+ +----------+ +----------+ +----------+ +----------+
+ | Agent-01 | | Agent-02 | | Agent-03 | | Agent-N  |
+ | youtube  | | trello   | | instagram| | server-N |
+ | health   | | health   | | health   | | health   |
+ | arch     | | arch     | | arch     | | arch     |
+ | complete | | complete | | complete | | complete |
+ | security | | security | | security | | security |
+ +----+-----+ +----+-----+ +----+-----+ +----+-----+
+      |            |            |            |
+      +------+-----+-----+------+
+             |
+ +-------------------------+
+ | Chain analysis + report |
+ +-------------------------+
+             |
+    +----------------+
+    | HTML + Fix     |
+    +----------------+
+```
+
+## Tests
+
+75+ tests across 6 test files:
+
+- **test_semgrep.py** — each vulnerable fixture detected, each benign fixture clean
+- **test_self_security.py** — 21 tests: our own code audited for vulnerabilities
+- **test_stress.py** — 1000/10000 findings, concurrent scans, unicode
+- **test_fuzzing.py** — Hypothesis property-based: any input, no crash
+- **test_edge_cases.py** — corrupt JSON, missing files, null bytes, timeouts
+- **test_models.py** + **test_formatters.py** — unit tests for core logic
+
+## Current Limitations
+
+- Plugin requires Claude Code with connected MCP servers
+- CLI requires semgrep for code analysis (graceful skip if not installed)
+- LLM analysis requires ANTHROPIC_API_KEY
+- Destructive tests intentionally skipped — read-only probing only
+- Source code analysis works for local servers; pip/npm packages may have limited access
+- Plugin report quality scales with model capability (Opus > Sonnet > Haiku)
+- False positive rate not yet measured on production MCP servers
+
+### Known False Positive Patterns
+
+- SSRF rule triggers on `httpx.get()` with URL built from config, not user input
+- Path traversal rule triggers on `open()` where path is validated but validation isn't recognized as sanitizer
+- Stdout pollution flags `print()` in `__main__` block (safe, not in MCP handler)
+
+## Docs
+
+The `docs/` folder is useful independently:
+
+- **[attack-playbook.md](docs/attack-playbook.md)** — 18 attack categories, 48+ CVEs, payloads and detection methods
+- **[best-practices.md](docs/best-practices.md)** — MCP server security checklist
+- **[reference-server.md](docs/reference-server.md)** — secure server templates (Python + Node.js)
+
+## References
+
+- [OWASP MCP Top 10](https://owasp.org/www-project-mcp-top-10/)
+- [Invariant Labs — Tool Poisoning Attacks](https://invariantlabs.ai/blog/mcp-security-notification-tool-poisoning-attacks)
+- [Trail of Bits — MCP Security Layer](https://blog.trailofbits.com/2025/07/28/we-built-the-security-layer-mcp-always-needed/)
+- [Palo Alto Unit 42 — MCP Attack Vectors](https://unit42.paloaltonetworks.com/model-context-protocol-attack-vectors/)
+- [OX Security — STDIO Design Flaw](https://www.ox.security/blog/the-mother-of-all-ai-supply-chains-critical-systemic-vulnerability-at-the-core-of-the-mcp/)
+- [NSA — MCP Security Guidance](https://www.nsa.gov/Portals/75/documents/Cybersecurity/CSI_MCP_SECURITY.pdf)
+- [Vulnerable MCP Project](https://vulnerablemcp.info/)
+
+## License
+
+[MIT](LICENSE)

redteam_mcp-0.2.0/mcp_redteam/__init__.py

@@ -0,0 +1,2 @@
+"""mcp-redteam: MCP server security auditor."""
+__version__ = "0.2.0"

redteam_mcp-0.2.0/mcp_redteam/cli.py

@@ -0,0 +1,132 @@
+import sys
+import typer
+from rich.console import Console
+from pathlib import Path
+from typing import Optional
+from enum import Enum
+from datetime import datetime
+
+app = typer.Typer(
+    name="mcp-redteam",
+    help="MCP server security auditor — deterministic engine + AI-native behavioral analysis",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+class OutputFormat(str, Enum):
+    terminal = "terminal"
+    json = "json"
+    sarif = "sarif"
+
+
+@app.command()
+def scan(
+    path: Path = typer.Argument(..., help="Path to MCP server source code"),
+    format: OutputFormat = typer.Option(OutputFormat.terminal, "--format", "-f", help="Output format"),
+    no_llm: bool = typer.Option(False, "--no-llm", help="Deterministic checks only (no LLM)"),
+    config: bool = typer.Option(True, "--config/--no-config", help="Run config health checks"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path"),
+    fail_on: Optional[str] = typer.Option(None, "--fail-on", help="Exit 1 if findings at this severity or above (critical, high)"),
+):
+    """Scan MCP server for security vulnerabilities."""
+    from mcp_redteam.models import ScanResult, ScanMetadata, Severity
+    from mcp_redteam.engine.semgrep_runner import run_semgrep, is_semgrep_available
+    from mcp_redteam.engine.config_scanner import scan_config
+    from mcp_redteam.formatters import format_sarif, format_json, format_terminal
+    from mcp_redteam.formatters.sarif import write_sarif
+    from mcp_redteam.formatters.json_fmt import write_json
+
+    scan_start = datetime.now()
+
+    path = path.resolve()  # VULN-08 fix: canonicalize path
+    if not path.exists():
+        console.print(f"[red]Error:[/red] path {path} does not exist")
+        raise typer.Exit(code=2)
+
+    findings = []
+
+    # Phase 0: Config health
+    if config:
+        console.print("[bold cyan]Phase 0:[/bold cyan] Config validation...")
+        config_findings = scan_config()
+        findings.extend(config_findings)
+        console.print(f"  {len(config_findings)} config issues found")
+
+    # Phase 1: Semgrep deterministic scan
+    semgrep_available = is_semgrep_available()
+    if semgrep_available:
+        console.print("[bold cyan]Phase 1:[/bold cyan] Semgrep analysis...")
+        semgrep_findings = run_semgrep(path)
+        findings.extend(semgrep_findings)
+        console.print(f"  {len(semgrep_findings)} code findings")
+    else:
+        console.print("[yellow]Phase 1:[/yellow] Semgrep not installed — skipping deterministic code scan")
+        console.print("  Install: [dim]pip install semgrep[/dim]")
+
+    # Phase 2: LLM behavioral analysis
+    if not no_llm:
+        from mcp_redteam.llm.analyzer import analyze_behavioral, is_llm_available
+        if is_llm_available():
+            console.print("[bold cyan]Phase 2:[/bold cyan] LLM behavioral analysis...")
+            llm_findings = analyze_behavioral(path)
+            findings.extend(llm_findings)
+            console.print(f"  {len(llm_findings)} behavioral findings")
+        else:
+            console.print("[yellow]Phase 2:[/yellow] No ANTHROPIC_API_KEY — skipping LLM analysis")
+            console.print("  Set: [dim]export ANTHROPIC_API_KEY=sk-...[/dim]")
+
+    # Build result
+    result = ScanResult(
+        metadata=ScanMetadata(
+            scan_start=scan_start,
+            scan_end=datetime.now(),
+            target_path=str(path),
+            mode="deterministic" if no_llm else "hybrid",
+            llm_enabled=not no_llm,
+            semgrep_available=semgrep_available,
+            files_scanned=sum(1 for _ in path.rglob("*.py")) + sum(1 for _ in path.rglob("*.ts")) + sum(1 for _ in path.rglob("*.js")) if path.is_dir() else 1,
+        ),
+        findings=findings,
+    )
+
+    # Output
+    if format == OutputFormat.terminal:
+        format_terminal(result, console)
+    elif format == OutputFormat.sarif:
+        sarif_str = format_sarif(result)
+        if output:
+            write_sarif(result, output)
+            console.print(f"[green]SARIF written to {output}[/green]")
+        else:
+            print(sarif_str)
+    elif format == OutputFormat.json:
+        json_str = format_json(result)
+        if output:
+            write_json(result, output)
+            console.print(f"[green]JSON written to {output}[/green]")
+        else:
+            print(json_str)
+
+    # Exit code for CI
+    if fail_on:
+        threshold = {"critical": Severity.CRITICAL, "high": Severity.HIGH}.get(fail_on.lower())
+        if threshold:
+            failing = [f for f in findings if _severity_rank(f.severity) >= _severity_rank(threshold)]
+            if failing:
+                raise typer.Exit(code=1)
+
+
+def _severity_rank(severity) -> int:
+    from mcp_redteam.models import Severity
+    ranks = {Severity.INFO: 0, Severity.LOW: 1, Severity.MEDIUM: 2, Severity.HIGH: 3, Severity.CRITICAL: 4}
+    return ranks.get(severity, 0)
+
+@app.command()
+def version():
+    """Show version."""
+    from mcp_redteam import __version__
+    console.print(f"mcp-redteam {__version__}")
+
+if __name__ == "__main__":
+    app()