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）掃描工具

密鑰掃描工具

軟件成分分析（SCA）工具

未來計劃集成的工具

偵察工具

• 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密鑰、令牌或憑證提交到配置文件中 - 請使用環境變量或秘密管理系統。