mcp-web-audit

一个基于 Node.js 的前端工程安全审计工具，支持对本地项目和远程仓库进行全面的依赖安全审计。

🔍 功能特性

• 🛡️ 全面审计: 审计前端工程的所有直接和间接依赖
• 🌐 多源支持: 支持本地工程和远程仓库（GitHub 等）的审计
• 📊 详细报告: 生成标准格式的 Markdown 审计报告
• 🔌 MCP 集成: 作为 MCP (Model Context Protocol) 服务器提供审计服务
• ⚡ 自动化: 全自动化的审计流程，无需手动干预
• 🚀 CLI 支持: 支持通过 npx 直接调用，无需安装

📋 审计内容

• 漏洞检测: 识别依赖包中的已知安全漏洞
• 版本分析: 检查依赖包版本的安全性和兼容性
• 依赖链分析: 深入分析间接依赖关系
• 风险评估: 按严重程度分类漏洞（Critical、High、Moderate、Low）
• 修复建议: 提供具体的修复方案和建议

🚀 快速开始

使用 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

🚀 CLI 使用说明

基本用法

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 服务器运行

作为 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 或联系维护者。