mcpwner

🚀 MCPwner

MCPwner是一款用于安全研究自动化的模型上下文协议（MCP）服务器，它能将安全测试工具集成到由大语言模型（LLM）驱动的工作流程中，为安全研究提供统一接口，助力发现和分析安全漏洞。

🚀 快速开始

MCPwner是一个模型上下文协议（MCP）服务器，它将安全测试工具集成到由大语言模型驱动的工作流程中。它为密钥扫描、静态分析（SAST）、软件成分分析（SCA）和漏洞研究（包括零日漏洞发现）提供了统一的接口。

你无需手动链接工具并将输出粘贴到你的大语言模型中，MCPwner会将结果标准化并直接流式传输到模型的工作上下文中。这使得在整个安全研究生命周期中（从识别已知漏洞到发现新的攻击向量）能够进行持续的推理、关联和攻击路径发现。

⚠️ 重要提示

本项目正在积极开发中。点击此处了解更多关于MCP的信息。

✨ 主要特性

• 🔧 统一接口：单个MCP服务器集成了多个安全工具（SAST、SCA、密钥检测）。
• 🤖 大语言模型集成：结构化输出格式（SARIF/JSON），可供AI助手直接使用。
• 🔍 持续分析：关联多个工具的发现结果，以识别攻击路径和零日漏洞。
• 🏗️ 多代理架构：专为跨安全阶段协作的专业代理而设计。
• 🐳 容器化执行：隔离的工具环境，可实现可重复的扫描。
• 💾 自动持久化：工作区和数据库元数据在容器重启后仍然保留。
• 🔌 可扩展：插件架构，可添加新的安全工具。

📦 安装指南

前提条件

系统要求：

• Docker引擎20.10及以上版本，Docker Compose 2.0及以上版本。
• 至少8GB内存（运行多个工具时建议16GB）。
• 20GB可用磁盘空间（安全工具镜像较大）。
• 支持的平台：Linux、macOS、Windows（使用WSL2）。

MCP客户端：

• Claude Desktop、Cursor、Kiro或任何MCP兼容的客户端。

安装步骤

1. 克隆仓库：

git clone https://github.com/yourusername/mcpwner.git
cd mcpwner

2. 配置服务器：

cp config/config.yaml.example config/config.yaml
# 根据需要编辑config/config.yaml

3. 启动服务：

docker-compose up -d --build

4. 验证服务是否正在运行：

docker-compose ps

连接你的IDE

一旦Docker容器运行起来，将MCPwner添加到你的MCP客户端：

配置文件位置：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• Cursor/Kiro：项目或设置目录中的mcp.json

一键安装（需要Docker运行）：

手动配置： 将以下内容添加到你的MCP配置文件中：

{
  "mcpServers": {
    "mcpwner": {
      "command": "docker",
      "args": ["exec", "-i", "mcpwner-server", "python", "src/server.py"],
      "env": {}
    }
  }
}

重启你的MCP客户端以加载新的服务器配置。

扫描本地项目

要扫描主机上的项目，可在docker-compose.yaml中添加一个卷，将项目挂载到容器中：

services:
  mcpwner:
    volumes:
      - /path/to/your/projects:/mnt/projects:ro

然后使用create_workspace工具，并设置：

• source_type="local"
• source="/mnt/projects/my-project"

💻 使用示例

扫描GitHub仓库中的密钥

"Scan https://github.com/example/repo for secrets"
→ MCPwner运行Gitleaks、TruffleHog、detect-secrets并关联发现结果

安全审计

"Run a security audit on my Python project"
→ MCPwner运行Bandit（SAST）、OSV-Scanner（SCA）和密钥扫描

攻击路径分析

"Find vulnerabilities in the authentication module"
→ MCPwner运行CodeQL查询，并与密钥和SCA结果进行交叉引用

📚 详细文档

集成工具

静态应用安全测试（SAST）扫描工具

| | | | | | | :--------------------------------------------: | :-----------------------------------------: | :--------------------------------------------: | :-------------------------------------------: | :-----------------------------------------------: | | CodeQL | Psalm | Gosec | Bandit | Semgrep |

| | | | :-------------------------------------------------------: | :------------------------------------: | | Brakeman | PMD |

密钥扫描工具

| | | | | | | :-----------------------------------------------------: | :-------------------------------------------------------------: | :----------------------------------------------------------: | :----------------------------------------------------: | :----------------------------------------------------: | | Gitleaks | TruffleHog | detect-secrets | Whispers | Hawk-Eye |

软件成分分析（SCA）工具

| | | | | :-----------------------------------------------------------------------------------------: | :------------------------------------------------------: | :----------------------------------------------------: | | Grype & Syft | OSV-Scanner | Retire.js |

未来计划集成的工具

侦察工具

• Amass、Subfinder、httpx、Katana、gau、Nmap、Arjun、FFUF、Akto

动态应用安全测试（DAST）工具

• OWASP ZAP、Wapiti、Nikto、SQLmap、SSRFmap、SSTImap、Nuclei、Dalfox、XSStrike、jwt_tool、Interactsh、Frida

基础设施与基础设施即代码（IaC）安全工具

• Prowler、Checkov、KICS、Terrascan、TFSec、Hadolint

漏洞利用与概念验证（PoC）开发工具

• Metasploit、Interactsh

数据持久化

MCPwner使用基于文件的存储在共享Docker卷（/workspaces/.metadata/）中自动持久化工作区和CodeQL数据库元数据，跨容器重启保留。无需配置，系统在启动时加载现有数据，并在每次操作后使用原子写入保存数据，以防止数据损坏。

工作区清理控制： cleanup_workspace工具提供精细控制：

• delete_files=True, delete_metadata=False - 释放磁盘空间但保留工作区历史记录（推荐）
• delete_files=True, delete_metadata=True - 完全删除工作区和元数据
• delete_files=False, delete_metadata=True - 从列表中移除但保留磁盘上的文件

备份：

# 备份整个工作区卷
docker run --rm -v mcpwner_workspaces:/data -v $(pwd):/backup \
  alpine tar czf /backup/workspaces-backup.tar.gz /data

# 恢复卷
docker run --rm -v mcpwner_workspaces:/data -v $(pwd):/backup \
  alpine tar xzf /backup/workspaces-backup.tar.gz -C /

架构

MCPwner使用基于HTTP的容器间通信，以支持未来的远程部署。虽然目前针对本地使用进行了优化，但该架构只需进行最小的修改即可适应远程服务器部署。

设计原则：

• 安全工具执行的容器隔离。
• 供大语言模型使用的标准化输出格式（SARIF/JSON）。
• 新工具的可扩展插件架构。
• 无状态API（记忆由用户管理）。

架构概述：

graph LR
    subgraph IDE[" "]
        LLM[🤖<br/>LLM]
        Client[MCP Client]
        LLM -.-> Client
    end

    Server[MCPwner Server]

    SAST[SAST Tools]
    Secrets[Secrets Scanning]
    SCA[SCA Tools]
    DAST[DAST Tools]
    Recon[Reconnaissance]
    IaC[IaC Security]
    Exploit[Exploitation]
    CodeQL[CodeQL Service]
    Linguist[Language Detection]

    Client -->|JSON-RPC 2.0| Server
    Server -->|HTTP| SAST
    Server -->|HTTP| Secrets
    Server -->|HTTP| SCA
    Server -->|HTTP| DAST
    Server -->|HTTP| Recon
    Server -->|HTTP| IaC
    Server -->|HTTP| Exploit
    Server -->|HTTP| CodeQL
    Server -->|HTTP| Linguist

    style LLM fill:#7C3AED,stroke:#5B21B6,stroke-width:3px,color:#fff
    style Client fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
    style Server fill:#F5A623,stroke:#C17D11,stroke-width:3px,color:#fff
    style SAST fill:#E74C3C,stroke:#C0392B,stroke-width:2px,color:#fff
    style Secrets fill:#9B59B6,stroke:#7D3C98,stroke-width:2px,color:#fff
    style SCA fill:#1ABC9C,stroke:#16A085,stroke-width:2px,color:#fff
    style DAST fill:#E91E63,stroke:#C2185B,stroke-width:2px,color:#fff
    style Recon fill:#00BCD4,stroke:#0097A7,stroke-width:2px,color:#fff
    style IaC fill:#8BC34A,stroke:#689F38,stroke-width:2px,color:#fff
    style Exploit fill:#FF5722,stroke:#E64A19,stroke-width:2px,color:#fff
    style CodeQL fill:#E67E22,stroke:#CA6F1E,stroke-width:2px,color:#fff
    style Linguist fill:#3498DB,stroke:#2874A6,stroke-width:2px,color:#fff
    style IDE fill:none,stroke:#ddd,stroke-width:2px,stroke-dasharray: 5 5

工作流程

数据流 - 分析结果：

sequenceDiagram
    participant LLM as 🤖 LLM
    participant MCP as MCP Client
    participant Server as MCPwner Server
    participant Tools as Security Tools

    LLM->>MCP: Request security scan
    MCP->>Server: Execute scan command
    Server->>Tools: Run analysis
    Tools-->>Server: Raw results
    Server-->>MCP: SARIF/JSON reports
    MCP-->>LLM: Structured findings
    Note over LLM: Correlate vulnerabilities<br/>Generate insights<br/>Suggest remediation

可用的MCP工具

MCPwner通过MCP接口提供以下工具：

工作区管理：

• create_workspace - 从本地路径、Git URL或GitHub仓库初始化扫描工作区。
• list_workspaces - 列出所有可用的工作区。
• cleanup_workspace - 删除工作区及相关数据。

SAST（静态分析）：

• sast_scan - 运行静态分析工具（CodeQL、Semgrep、Bandit、Gosec等）。
• sast_get_report - 获取SAST扫描结果。
• sast_list_tools - 列出可用的SAST工具。

密钥检测：

• secrets_scan - 运行密钥扫描工具（Gitleaks、TruffleHog等）。
• secrets_get_report - 获取密钥扫描结果。
• secrets_list_tools - 列出可用的密钥扫描工具。

SCA（软件成分分析）：

• sca_scan - 分析依赖项的漏洞（Grype、OSV-Scanner等）。
• sca_get_report - 获取SCA扫描结果。
• sca_list_tools - 列出可用的SCA工具。

CodeQL特定工具：

• codeql_detect_languages - 检测代码库中的语言。
• codeql_create_database - 创建CodeQL数据库进行分析。
• codeql_list_databases - 列出可用的CodeQL数据库。
• codeql_list_query_packs - 列出可用的查询包。
• codeql_execute_query - 运行特定的CodeQL查询。

健康与监控：

• health_check - 检查服务器和工具的可用性。
• list_tools - 列出所有可用的工具及其状态。

🔧 技术细节

架构设计

MCPwner采用基于HTTP的容器间通信，支持未来的远程部署。当前架构针对本地使用进行了优化，但可通过最小的修改适应远程服务器部署。其设计原则包括容器隔离、标准化输出格式、可扩展插件架构和无状态API。

数据持久化

MCPwner使用基于文件的存储在共享Docker卷（/workspaces/.metadata/）中自动持久化工作区和CodeQL数据库元数据。系统在启动时加载现有数据，并在每次操作后使用原子写入保存数据，以防止数据损坏。

工作流程

MCPwner的工作流程涉及大语言模型（LLM）、MCP客户端、MCPwner服务器和安全工具之间的交互。LLM发起安全扫描请求，MCP客户端将请求传递给服务器，服务器调用安全工具进行分析，工具返回原始结果，服务器将结果转换为SARIF/JSON报告返回给MCP客户端，最终客户端将结构化的发现结果提供给LLM进行关联、洞察生成和建议修复。

📄 许可证

本项目采用 Apache 2.0 许可证。

贡献说明

欢迎贡献代码！在提交拉取请求之前，请查看 贡献指南。

优先领域：

• 测试基础设施（端到端测试和单元测试）。
• 容器生命周期管理和优化。
• 多阶段Docker构建以减小镜像大小。
• 增强错误处理和超时机制。
• 更多安全工具集成。

贡献指南：

• 提交范围可控的聚焦拉取请求。
• 为新功能添加测试。
• 遵循现有的代码风格和模式。
• 根据需要更新文档。

请查看 未来工具 部分了解我们的开发路线图。

安全注意事项

MCPwner执行的安全工具可能会执行侵入性操作。仅在你拥有或获得明确测试许可的系统和代码库上使用 - 未经授权的访问是非法的。将MCP服务器的访问权限限制为授权用户，并考虑在生产部署中进行网络隔离。在运行扫描之前审查工具配置，因为某些工具可能会产生大量网络流量或系统负载。记录工具执行和结果，同时要注意安全扫描可能会在监控系统中触发警报。在报告使用MCPwner发现的漏洞时，请遵循负责任的披露做法。定期更新Docker镜像并扫描容器以查找漏洞。切勿将API密钥、令牌或凭证提交到配置文件中 - 请使用环境变量或秘密管理系统。