MCP Web Audit

🚀 mcp-web-audit

mcp-web-audit 是一個基於 Node.js 的前端工程安全審計工具，它支持對本地項目和遠程倉庫進行全面的依賴安全審計，能有效保障前端項目的安全性。

🚀 快速開始

使用 npx（推薦）

無需安裝，直接使用：

# 審計本地項目
npx mcp-web-audit /path/to/your/project

# 審計遠程倉庫
npx mcp-web-audit https://github.com/user/repo

# 指定輸出文件
npx mcp-web-audit /path/to/project -o ./my-audit.md

# 查看幫助
npx mcp-web-audit --help

# 查看版本
npx mcp-web-audit --version

全局安裝

# 全局安裝
npm install -g mcp-web-audit

# 使用命令
mcp-web-audit /path/to/your/project

本地安裝開發版本

# 克隆倉庫
git clone https://github.com/shenzhihao/mcp-web-audit.git
cd mcp-web-audit

# 安裝依賴
npm install

# 本地測試
node bin/cli.js /path/to/test/project

✨ 主要特性

• 🛡️ 全面審計：審計前端工程的所有直接和間接依賴。
• 🌐 多源支持：支持本地工程和遠程倉庫（GitHub 等）的審計。
• 📊 詳細報告：生成標準格式的 Markdown 審計報告。
• 🔌 MCP 集成：作為 MCP (Model Context Protocol) 服務器提供審計服務。
• ⚡ 自動化：全自動化的審計流程，無需手動干預。
• 🚀 CLI 支持：支持通過 npx 直接調用，無需安裝。

📋 審計內容

• 漏洞檢測：識別依賴包中的已知安全漏洞。
• 版本分析：檢查依賴包版本的安全性和兼容性。
• 依賴鏈分析：深入分析間接依賴關係。
• 風險評估：按嚴重程度分類漏洞（Critical、High、Moderate、Low）。
• 修復建議：提供具體的修復方案和建議。

💻 使用示例

基本用法

npx mcp-web-audit [options] <項目路徑>

參數說明

• <項目路徑>：要審計的項目路徑（本地絕對路徑或遠程倉庫 URL）。

選項

• -o, --output <文件>：指定輸出報告的文件路徑 (默認: ./audit-report.md)。
• -h, --help：顯示幫助信息。
• -v, --version：顯示版本信息。

使用示例

# 審計當前目錄
npx mcp-web-audit .

# 審計指定本地項目
npx mcp-web-audit /Users/username/my-project

# 審計GitHub倉庫
npx mcp-web-audit https://github.com/facebook/react

# 指定輸出文件名
npx mcp-web-audit ./my-project -o security-report.md

# 查看幫助信息
npx mcp-web-audit --help

作為 MCP 服務器運行

node src/mcpServer.js

編程式調用

import { auditPackage } from "mcp-web-audit";

// 審計本地項目
await auditPackage("/path/to/your/project", "./audit-report.md");

// 審計遠程倉庫
await auditPackage("https://github.com/user/repo", "./audit-report.md");

📊 審計報告示例

生成的審計報告包含以下信息：

• 項目概述：項目名稱、版本等基本信息。
• 漏洞彙總：按嚴重程度統計的漏洞數量。
• 詳細漏洞列表：每個漏洞的詳細信息，包括：
  • 漏洞描述
  • 影響的包和版本
  • 嚴重程度評級
  • 修復建議
  • 相關鏈接

📚 詳細文檔

要求

• Node.js：>= 14.0.0。
• 網絡：審計遠程倉庫時需要網絡連接。
• 磁盤空間：至少 100MB 空閒空間（用於臨時文件）。

項目結構

src/
├── audit/              # 審計核心模塊
│   ├── currentAudit.js  # 當前項目審計
│   ├── getDepChain.js   # 依賴鏈分析
│   ├── index.js         # 審計主入口
│   ├── normalizeAuditResult.js  # 結果標準化
│   ├── npmAudit.js      # NPM 審計
│   └── remoteAudit.js   # 遠程審計
├── common/             # 通用工具
│   └── utils.js        # 工具函數
├── entry/              # 程序入口
│   └── index.js        # 主要 API 入口
├── generateLock/       # Lock 文件生成
│   ├── generateLock.js # Lock 文件生成邏輯
│   └── index.js        # 模塊入口
├── main/               # 主程序
│   └── index.js        # 主程序入口
├── parseProject/       # 項目解析
│   ├── index.js        # 解析入口
│   ├── parseLocalProject.js   # 本地項目解析
│   └── parseRemoteProject.js  # 遠程項目解析
├── render/             # 報告渲染
│   ├── index.js        # 渲染入口
│   ├── markdown.js     # Markdown 渲染
│   └── test/           # 測試文件
├── workDir/            # 工作目錄管理
│   └── index.js        # 工作目錄操作
└── mcpServer.js        # MCP 服務器

API 參考

auditPackage(projectRoot, savePath)

審計指定項目的所有依賴包。 參數：

• projectRoot (string)：項目根目錄的絕對路徑或遠程倉庫 URL。
• savePath (string)：審計報告保存路徑。 示例：

// 本地項目
await auditPackage("/Users/username/my-project", "./audit.md");

// 遠程倉庫
await auditPackage("https://github.com/facebook/react", "./react-audit.md");

審計報告

生成的審計報告包含以下信息：

• 項目概述：項目名稱、版本等基本信息。
• 漏洞彙總：按嚴重程度統計的漏洞數量。
• 詳細漏洞列表：每個漏洞的詳細信息，包括：
  • 漏洞描述
  • 影響的包和版本
  • 嚴重程度評級
  • 修復建議
  • 相關鏈接

🔧 技術細節

技術棧

• 運行環境：Node.js (ES Modules)。
• 核心依賴：
  • @modelcontextprotocol/sdk：MCP 協議支持。
  • ejs：模板引擎。
  • zod：數據驗證。

安全審計流程

1. 項目解析：解析項目的 package.json 文件。
2. 依賴分析：分析所有直接和間接依賴。
3. Lock 文件生成：生成依賴鎖定文件。
4. 安全掃描：使用 npm audit 進行安全掃描。
5. 結果標準化：將審計結果標準化處理。
6. 報告生成：生成 Markdown 格式的審計報告。

🤝 貢獻指南

歡迎提交 Issue 和 Pull Request 來幫助改進這個項目。

📄 許可證

ISC License

📞 支持

如果您在使用過程中遇到問題，請提交 Issue 或聯繫維護者。