JinDaGe - mcp-web-audit MCP Details

article

README

🚀 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：数据验证。

安全审计流程

项目解析：解析项目的 package.json 文件。
依赖分析：分析所有直接和间接依赖。
Lock 文件生成：生成依赖锁定文件。
安全扫描：使用 npm audit 进行安全扫描。
结果标准化：将审计结果标准化处理。
报告生成：生成 Markdown 格式的审计报告。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来帮助改进这个项目。

📄 许可证

ISC License

📞 支持

如果您在使用过程中遇到问题，请提交 Issue 或联系维护者。

mcp-web-audit