Metadata-Version: 2.4
Name: mcp-agent-security-scanner
Version: 0.1.0
Summary: Security scanner for MCP (Model Context Protocol) server configurations and AI agent tool permissions.
Author: MCP-Scan Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/martian7777/mcp-agent-security-scanner
Project-URL: Documentation, https://github.com/martian7777/mcp-agent-security-scanner/tree/main/docs
Project-URL: Repository, https://github.com/martian7777/mcp-agent-security-scanner
Project-URL: Issues, https://github.com/martian7777/mcp-agent-security-scanner/issues
Keywords: mcp,security,scanner,ai-agents,model-context-protocol,devsecops,sarif,owasp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
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: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: server
Requires-Dist: fastapi>=0.100.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.22.0; extra == "server"
Requires-Dist: python-multipart>=0.0.6; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: httpx>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Provides-Extra: all
Requires-Dist: mcp-agent-security-scanner[dev,server]; extra == "all"
Dynamic: license-file

<div align="center">

# 🔒 MCP-Scan

**Security scanner for MCP server configurations and AI agent tool permissions.**

Detect dangerous shell commands, exposed API keys, over-permissive file access, high-risk tools, and prompt injection patterns — before they reach production.

[![PyPI version](https://img.shields.io/pypi/v/mcp-scan?style=flat-square&color=6366f1)](https://pypi.org/project/mcp-scan/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-scan?style=flat-square)](https://pypi.org/project/mcp-scan/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/martian7777/mcp-agent-security-scanner/mcp-scan-ci.yml?style=flat-square&label=CI)](https://github.com/martian7777/mcp-agent-security-scanner/actions)

[Quick Start](#-quick-start) · [Example Output](#-example-output) · [Rules](#-scanning-rules) · [Library API](#-python-library-api) · [Dashboard](#-web-dashboard) · [CI/CD](#%EF%B8%8F-cicd-integration) · [Contributing](#-contributing)

</div>

---

## 🚨 The Problem

AI agents are now connecting to tools, files, GitHub, Slack, Gmail, Notion, databases, and internal systems via MCP (Model Context Protocol). **This creates serious security risk:**

- 🔓 Unrestricted shell access (`bash -c "$USER_INPUT"`)
- 🔑 API keys and tokens hard-coded in configuration files
- 📁 Over-permissive file system access (`/`, `/etc/shadow`, `~/.ssh`)
- 📧 Tools that can send emails, delete files, or drop database tables with no confirmation
- 💉 Prompt injection patterns that could hijack agent behavior
- ⚠️ Binaries running from untrusted paths (`/tmp/Downloads/sketchy-tool`)

**OWASP now has an [MCP Top 10](https://owasp.org/www-project-mcp-top-10/)** covering tool poisoning, excessive agency, and context spoofing. GitHub added secret scanning support for MCP workflows. The attack surface is real and growing.

**MCP-Scan catches these risks in seconds.**

---

## ⚡ Quick Start

### Install

```bash
pip install mcp-scan
```

### Scan

```bash
mcp-scan scan ./mcp-config.json
```

### That's it. 3 lines.

---

## 📥 Example Input

Here's a dangerous MCP configuration:

```json
{
  "mcpServers": {
    "terminal.run": {
      "command": "bash",
      "args": ["-c", "eval $USER_INPUT"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-abc123def456ghi789jkl012mno"
      }
    },
    "gmail.send": {
      "command": "node",
      "args": ["gmail-mcp-server", "--no-confirm"],
      "env": {
        "GMAIL_TOKEN": "ya29.a0AfH6SMBx_FAKE_TOKEN"
      }
    },
    "filesystem": {
      "command": "/tmp/Downloads/sketchy-binary",
      "args": ["/", "/etc/shadow", "/root/.ssh"]
    }
  }
}
```

## 📊 Example Output

```
┌──────────────────────────────────────────────────────────┐
│  MCP Security Scan Report                                │
│  File: mcp-config.json                                   │
│  Version: 0.1.0                                          │
└──────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────┐
│  Findings: 8 HIGH | 3 MEDIUM | 3 LOW  (14 total)        │
└──────────────────────────────────────────────────────────┘

 Severity │ Rule    │ Server         │ Message
──────────┼─────────┼────────────────┼──────────────────────────────────────
 HIGH     │ MCP-001 │ terminal.run   │ Uses dangerous command: "bash"
 HIGH     │ MCP-002 │ terminal.run   │ OpenAI API key exposed in env
 HIGH     │ MCP-006 │ gmail.send     │ High-risk tool: email sending
 HIGH     │ MCP-008 │ filesystem     │ Binary from untrusted path: /tmp/
 MEDIUM   │ MCP-003 │ filesystem     │ Access to sensitive path: /etc/shadow
 MEDIUM   │ MCP-003 │ filesystem     │ Access to sensitive path: /root/.ssh
 LOW      │ MCP-005 │ terminal.run   │ No allowedTools defined
```

---

## 🔍 Scanning Rules

| Rule | Name | Severity | What it catches |
|------|------|----------|----------------|
| **MCP-001** | Dangerous Shell Commands | 🔴 HIGH | `bash`, `powershell`, `eval`, `sudo`, `ssh`, piped `curl` |
| **MCP-002** | Exposed Secrets | 🔴 HIGH | OpenAI keys, GitHub PATs, AWS keys, Slack tokens, private keys |
| **MCP-003** | Over-permissive Paths | 🟡 MEDIUM | `/`, `/etc`, `~/.ssh`, `C:\Windows\System32` |
| **MCP-004** | Untrusted MCP Server | 🟡 MEDIUM | Binaries from `/tmp`, `Downloads`, unverified sources |
| **MCP-005** | Missing Tool Allowlist | 🔵 LOW | No `allowedTools` restriction → full agent access |
| **MCP-006** | High-Risk Tools | 🔴 HIGH | Email send, file delete, DB write, Slack post without gates |
| **MCP-007** | Prompt Injection | 🟡 MEDIUM | "Ignore previous instructions", template injection, jailbreaks |
| **MCP-008** | Unsafe Binary Execution | 🔴 HIGH | Executing from `/tmp/`, `Downloads/`, `.cache/` |

---

## 🐍 Python Library API

Use `mcp-scan` programmatically in your own tools:

```python
from mcp_scan import scan_config, scan_file, ScanPolicy

# Scan a config dictionary
result = scan_config({
    "mcpServers": {
        "my-server": {
            "command": "bash",
            "args": ["-c", "rm -rf /"]
        }
    }
})

print(result.has_errors)        # True
print(result.highest_severity)  # "HIGH"
print(result.total_findings)    # 3

for finding in result.findings:
    print(f"[{finding.severity}] {finding.rule_id}: {finding.message}")

# Scan with a custom policy
policy = ScanPolicy(
    allowed_commands=["node", "python"],
    trusted_servers=["@modelcontextprotocol/"],
    ignored_rules=["MCP-005"],
)
result = scan_config(config, policy=policy)

# Scan a file directly
result = scan_file("./mcp-config.json")

# Export to SARIF
from mcp_scan import to_sarif_json
print(to_sarif_json(result))
```

---

## 🌐 Web Dashboard

Start the built-in dashboard:

```bash
pip install mcp-scan[server]
mcp-scan serve
```

Open `http://localhost:8000` — paste your config, click **Scan Now**, and get instant visual results with severity cards, findings table, and SARIF export.

---

## 🐳 Docker

```bash
cd docker
docker compose up --build
```

Dashboard available at `http://localhost:8000`. Mount your config files:

```bash
docker run --rm -v $(pwd):/configs mcp-scan mcp-scan scan /configs/mcp-config.json
```

---

## ⚙️ CI/CD Integration

### GitHub Actions

```yaml
- name: Install mcp-scan
  run: pip install mcp-scan

- name: Scan MCP configs
  run: mcp-scan scan ./mcp-config.json --fail-on HIGH

- name: Upload SARIF (optional)
  run: mcp-scan scan ./mcp-config.json --output sarif > results.sarif
  
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
```

The scanner exits with code **1** when HIGH-severity findings are detected, automatically failing your CI pipeline.

---

## 📋 Custom Scanning Policy

Create `mcp-policy.yaml` to customize behavior:

```yaml
trusted_servers:
  - "@modelcontextprotocol/"
  - "npx"

allowed_commands:
  - "node"
  - "python"

ignored_rules:
  - "MCP-005"

max_severity: HIGH
```

```bash
mcp-scan scan ./config.json --policy ./mcp-policy.yaml
```

---

## 🏗️ Architecture

```
Input (CLI / API / Library)
    ↓
Parser (JSON / YAML → Pydantic McpConfig)
    ↓
Engine (8 security rules + policy filtering)
    ↓
Output (Rich terminal / JSON / SARIF / Dashboard)
```

See [docs/architecture.md](docs/architecture.md) for the full architecture diagram and threat model.

---

## 🎯 Real Use Cases

- **AI coding agents** — Teams using Cursor, Windsurf, or Claude Code with MCP servers need to audit tool permissions before granting agents access to codebases and infrastructure.
- **Enterprise AI deployments** — Companies rolling out Claude, GPT, or Gemini with tool use need security gates for email, Slack, database, and file system access.
- **Platform engineering** — Platform teams can run `mcp-scan` in CI/CD to enforce security policies across all MCP configurations in the org.
- **Compliance** — Security teams can generate SARIF reports for audit trails and integrate with GitHub Advanced Security.

---

## 🗺️ Roadmap

- [ ] **Custom rule engine** — Write your own rules in YAML
- [ ] **Continuous monitoring** — Watch config files for changes and alert
- [ ] **Slack/Discord alerts** — Send notifications when new risks are found
- [ ] **VS Code extension** — Inline warnings in your editor
- [ ] **MCP runtime analysis** — Monitor actual tool invocations at runtime
- [ ] **Organization-wide policies** — Centralized policy management
- [ ] **SBOM integration** — Software Bill of Materials for MCP server dependencies

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
git clone https://github.com/martian7777/mcp-agent-security-scanner.git
cd mcp-scan
pip install -e ".[all]"
pytest
```

### Adding a New Rule

1. Add your detection function to `mcp_scan/engine.py`
2. Register it in the `ALL_RULES` list
3. Add tests in `tests/test_engine.py`
4. Update the rule table in this README

---

## 🏷️ Good First Issues

Looking to contribute? Start here:

1. **Add GitLab CI template** — Create a `.gitlab-ci.yml` example for GitLab users
2. **Add `--config-format` auto-detection** — Detect JSON vs YAML from file content, not just extension
3. **Add Slack webhook rule** — Detect Slack webhook URLs (`https://hooks.slack.com/...`) in configs
4. **Improve remediation messages** — Make fix suggestions more specific and actionable
5. **Add `--quiet` flag** — Only print findings, no header/footer

---

## 📄 License

MIT — see [LICENSE](LICENSE).

---

<div align="center">

**Built for teams shipping AI agents safely.**

[⭐ Star on GitHub](https://github.com/martian7777/mcp-agent-security-scanner) · [Report a Bug](https://github.com/martian7777/mcp-agent-security-scanner/issues) · [Request a Feature](https://github.com/martian7777/mcp-agent-security-scanner/issues)

</div>
