Audit Project Server

一个用于审计项目依赖安全性的工具，支持本地和远程 GitHub 项目，可生成多种格式的审计报告。

✨ 特性

• 🔍 支持多种项目源：本地项目、GitHub 远程仓库
• 📊 多种输出格式：Markdown、HTML、纯文本、可视化仪表板
• 🛡️ 安全审计：使用 npm audit 进行依赖安全扫描
• 🔄 智能依赖处理：自动过滤特殊协议依赖（git、file、link 等）
• 📈 详细报告：包含漏洞统计、修复建议、跳过的依赖等信息
• 🤖 MCP 集成：可作为 Model Context Protocol 服务器使用

📦 安装

作为 npm 包安装

npm install audit-project-server

作为 mcp 服务使用

{
  "mcpServers": {
    "audit-project-server": {
      "timeout": 60,
      "command": "npx",
      "args": [
        "-y",
        "audit-project-server"
      ],
      "type": "stdio",
      "disabled": false
    }
  }
}

从源码安装

git clone https://github.com/yourusername/audit-project.git
cd audit-project
npm install

🚀 快速开始

作为 CLI 工具使用

import { auditProject } from 'audit-project-server';

// 审计本地项目
await auditProject('./my-project', './audit-result.md', 'md');

// 审计 GitHub 项目
await auditProject('https://github.com/facebook/react/tree/v19.2.3', './react-audit.html', 'html');

作为 MCP 服务器使用

# 启动 MCP 服务器
npm start

📋 使用方法

基本参数

| 参数 | 类型 | 说明 | 示例 | |------|------|------|------| | projectPath | string | 项目路径（支持本地和远程） | ./my-project 或 https://github.com/owner/repo | | savePath | string | 保存路径（不含扩展名） | ./audit-result | | outputFormat | string | 输出格式 | md, html, txt, dashboard |

输出格式说明

• md：Markdown 格式，适合文档和 GitHub
• html：HTML 页面，适合浏览器查看
• txt：纯文本格式，适合终端查看
• dashboard：可视化仪表板，带图表和交互

🔧 工作原理

1. 创建工作目录：在临时目录中创建工作空间
2. 获取 package.json：
   • 本地项目：直接读取文件
   • GitHub 项目：通过 GitHub API 获取
3. 过滤特殊依赖：识别并跳过特殊协议依赖（git、file、link 等）
4. 生成 package-lock.json：使用 npm install --package-lock-only
5. 执行安全审计：运行 npm audit --json
6. 渲染报告：根据指定格式生成报告
7. 清理工作目录：删除临时文件

📊 报告内容

生成的审计报告包含以下部分：

1. 项目信息

• 项目名称和版本
• 审计时间和工具

2. 跳过的依赖

• 特殊协议依赖（git、file、link 等）
• 非正常版本依赖（latest、next、beta 等）
• 跳过原因和建议

3. 漏洞统计

• 按严重级别分类（严重、高、中、低、信息）
• 依赖类型统计（生产、开发、可选、peer）

4. 详细漏洞列表

• 每个漏洞的详细信息
• 受影响版本范围
• 修复建议和可用版本
• CVSS 评分和 CWE 标识

5. 修复建议总结

• 可用的修复命令
• 替代方案建议

🤝 作为 MCP 服务器使用

启动服务器

npm start

⚙️ 配置选项

环境变量

| 变量名 | 说明 | 默认值 | |--------|------|--------| | NPM_REGISTRY | npm 注册表地址 | https://registry.npmjs.org |

npm 配置

项目使用以下 npm 命令选项：

• --package-lock-only：只生成 package-lock.json
• --ignore-scripts：忽略 package.json 中的脚本
• --force：强制安装，忽略冲突

常见问题

1. GitHub 项目无法访问

   • 检查网络连接
   • 确认仓库是公开的
   • 确认分支或标签存在

2. npm audit 返回错误

   • 检查 npm 版本（需要 npm 6+）
   • 确认网络可以访问 npm 注册表
   • 检查项目依赖是否合法

3. 特殊依赖被跳过

   • 这是预期行为，特殊协议依赖无法通过 npm audit 审计
   • 建议手动检查这些依赖的安全性

调试模式

# 设置调试环境变量
npm start

📄 许可证

本项目采用 ISC 许可证。详见 LICENSE 文件。