audit-project-server 1.0.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Jackmu
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# Audit Project Server
+
+一个用于审计项目依赖安全性的工具，支持本地和远程 GitHub 项目，可生成多种格式的审计报告。
+
+## ✨ 特性
+
+- 🔍 **支持多种项目源**：本地项目、GitHub 远程仓库
+- 📊 **多种输出格式**：Markdown、HTML、纯文本、可视化仪表板
+- 🛡️ **安全审计**：使用 `npm audit` 进行依赖安全扫描
+- 🔄 **智能依赖处理**：自动过滤特殊协议依赖（git、file、link 等）
+- 📈 **详细报告**：包含漏洞统计、修复建议、跳过的依赖等信息
+- 🤖 **MCP 集成**：可作为 Model Context Protocol 服务器使用
+
+## 📦 安装
+
+### 作为 npm 包安装
+
+```bash
+npm install audit-project-server
+```
+
+### 作为 mcp 服务使用
+
+```json
+{
+  "mcpServers": {
+    "audit-project-server": {
+      "timeout": 60,
+      "command": "npx",
+      "args": [
+        "-y",
+        "audit-project-server"
+      ],
+      "type": "stdio",
+      "disabled": false
+    }
+  }
+}
+```
+
+### 从源码安装
+
+```bash
+git clone https://github.com/yourusername/audit-project.git
+cd audit-project
+npm install
+```
+
+## 🚀 快速开始
+
+### 作为 CLI 工具使用
+
+```javascript
+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 服务器使用
+
+```bash
+# 启动 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 服务器使用
+
+### 启动服务器
+
+```bash
+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 审计
+   - 建议手动检查这些依赖的安全性
+
+### 调试模式
+
+```bash
+# 设置调试环境变量
+npm start
+```
+
+## 📄 许可证
+
+本项目采用 ISC 许可证。详见 [LICENSE](LICENSE) 文件。

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "audit-project-server",
+  "version": "1.0.0",
+  "description": "A tool for auditing project dependency security, supporting local and remote GitHub projects with multiple output formats (Markdown, HTML, Text, Dashboard). Can be used as an npm package or MCP server.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./server": "./src/server.js"
+  },
+  "scripts": {
+    "start": "node ./src/server.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {},
+  "keywords": [
+    "audit",
+    "package-audit",
+    "npm-audit",
+    "github",
+    "mcp",
+    "model-context-protocol",
+    "security-audit",
+    "dependency-check"
+  ],
+  "author": "Jackmu",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackmu01/audit_project_mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jackmu01/audit_project_mcp/issues"
+  },
+  "homepage": "https://github.com/jackmu01/audit_project_mcp#readme",
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=8.0.0"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ]
+}

package/src/index.js

@@ -0,0 +1,31 @@
+import {
+  createdDirectory,
+  deleteDirectory,
+  getPackageJsonInfo,
+  generatePackageLockJson,
+  projectAudit,
+  renderAuditResultByFormat,
+} from "./utils.js";
+
+export async function auditProject(projectPath, savePath, outputFormat = "md") {
+  // 1.创建工作目录
+  const workDir = await createdDirectory();
+  // 2.找到目录的Package.json文件
+  const packageJson = await getPackageJsonInfo(projectPath);
+  // 3.根据Package.json文件内容，生成package-lock.json文件
+  const generateResult = await generatePackageLockJson(workDir, packageJson);
+  // 添加跳过的依赖信息到packageJson中，以便在渲染时使用
+  packageJson._skippedDependencies = generateResult.skippedDependencies;
+  // 4.在work 工作目录下执行npm audit命令
+  const auditResult = await projectAudit(workDir);
+  // 5.根据输出格式渲染审计结果
+  const result = await renderAuditResultByFormat(
+    auditResult,
+    packageJson,
+    outputFormat,
+    savePath
+  );
+  // 6.删除工作目录
+  await deleteDirectory(workDir);
+  return result;
+}

package/src/render/renderAuditResult.js

@@ -0,0 +1,229 @@
+import fs from "fs";
+
+/**
+ * 渲染npm audit结果到Markdown格式
+ * @param {string} auditResult JSON格式的npm audit结果
+ * @param {Object} packageJsonInfo package.json文件内容
+ * @returns {string} Markdown格式的报告
+ */
+export async function renderAuditResult(
+  auditResult,
+  packageJsonInfo,
+  savePath,
+) {
+  try {
+    const auditData = JSON.parse(auditResult);
+
+    // 检查是否有错误
+    if (auditData.error) {
+      return `# NPM Audit 报告\n\n❌ **错误**: ${auditData.error}\n\n`;
+    }
+
+    // 准备Markdown内容
+    let markdown = `# NPM Audit 安全审计报告\n\n`;
+
+    // 项目信息
+    markdown += `## 项目信息\n`;
+    markdown += `- **项目名称**: ${packageJsonInfo.name || "未知"}\n`;
+    markdown += `- **项目版本**: ${packageJsonInfo.version || "未知"}\n`;
+    markdown += `- **审计时间**: ${new Date().toLocaleString("zh-CN")}\n`;
+    markdown += `- **审计工具**: npm audit\n\n`;
+
+    // 跳过的依赖信息
+    if (packageJsonInfo._skippedDependencies) {
+      const skipped = packageJsonInfo._skippedDependencies;
+      let totalSkipped = 0;
+      let skippedDetails = [];
+      
+      // 统计跳过的依赖
+      const depTypes = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+      for (const depType of depTypes) {
+        if (skipped[depType] && skipped[depType].length > 0) {
+          totalSkipped += skipped[depType].length;
+          skippedDetails.push(...skipped[depType].map(dep => ({
+            ...dep,
+            type: depType
+          })));
+        }
+      }
+      
+      if (totalSkipped > 0) {
+        markdown += `## 跳过的依赖 (${totalSkipped}个)\n\n`;
+        markdown += `⚠️ **注意**: 以下依赖因使用特殊协议或非正常版本而被跳过审计：\n\n`;
+        
+        // 按依赖类型分组显示
+        for (const depType of depTypes) {
+          if (skipped[depType] && skipped[depType].length > 0) {
+            const typeName = {
+              'dependencies': '生产依赖',
+              'devDependencies': '开发依赖',
+              'peerDependencies': 'Peer依赖',
+              'optionalDependencies': '可选依赖'
+            }[depType] || depType;
+            
+            markdown += `### ${typeName} (${skipped[depType].length}个)\n`;
+            markdown += `| 包名 | 版本 | 跳过原因 |\n`;
+            markdown += `|------|------|----------|\n`;
+            
+            for (const dep of skipped[depType]) {
+              markdown += `| ${dep.name} | \`${dep.version}\` | ${dep.reason} |\n`;
+            }
+            markdown += `\n`;
+          }
+        }
+        
+        markdown += `**说明**:\n`;
+        markdown += `- **link:** 协议: 指向本地目录的符号链接\n`;
+        markdown += `- **file:** 协议: 指向本地文件的依赖\n`;
+        markdown += `- **git:** 协议: 指向Git仓库的依赖\n`;
+        markdown += `- **非正常版本**: 如 "latest", "next", "beta" 等非semver版本\n`;
+        markdown += `- **URL格式**: 直接指向URL的依赖\n\n`;
+        markdown += `这些依赖无法通过npm audit进行安全审计，建议手动检查其安全性。\n\n`;
+      }
+    }
+
+    // 漏洞统计摘要
+    const metadata = auditData.metadata;
+    if (metadata && metadata.vulnerabilities) {
+      const vulnStats = metadata.vulnerabilities;
+      markdown += `## 漏洞统计摘要\n`;
+      markdown += `| 严重级别 | 数量 |\n`;
+      markdown += `|----------|------|\n`;
+      markdown += `| **严重 (critical)** | ${vulnStats.critical || 0} |\n`;
+      markdown += `| **高 (high)** | ${vulnStats.high || 0} |\n`;
+      markdown += `| **中 (moderate)** | ${vulnStats.moderate || 0} |\n`;
+      markdown += `| **低 (low)** | ${vulnStats.low || 0} |\n`;
+      markdown += `| **信息 (info)** | ${vulnStats.info || 0} |\n`;
+      markdown += `| **总计** | **${vulnStats.total || 0}** |\n\n`;
+
+      // 依赖统计
+      const depStats = metadata.dependencies;
+      if (depStats) {
+        markdown += `## 依赖统计\n`;
+        markdown += `- **生产依赖**: ${depStats.prod || 0}\n`;
+        markdown += `- **开发依赖**: ${depStats.dev || 0}\n`;
+        markdown += `- **可选依赖**: ${depStats.optional || 0}\n`;
+        markdown += `- **Peer依赖**: ${depStats.peer || 0}\n`;
+        markdown += `- **总依赖数**: ${depStats.total || 0}\n\n`;
+      }
+    }
+
+    // 详细漏洞列表
+    const vulnerabilities = auditData.vulnerabilities;
+    if (vulnerabilities && Object.keys(vulnerabilities).length > 0) {
+      markdown += `## 详细漏洞列表\n\n`;
+
+      Object.entries(vulnerabilities).forEach(([pkgName, vuln]) => {
+        const severity = vuln.severity || "unknown";
+        const severityEmoji =
+          {
+            critical: "🔴",
+            high: "🟠",
+            moderate: "🟡",
+            low: "🟢",
+            info: "🔵",
+          }[severity] || "⚪";
+
+        markdown += `### ${severityEmoji} ${pkgName} (${severity.toUpperCase()})\n`;
+        markdown += `| 属性 | 值 |\n`;
+        markdown += `|------|-----|\n`;
+        markdown += `| **严重级别** | ${severity} |\n`;
+        markdown += `| **是否直接依赖** | ${vuln.isDirect ? "是" : "否"} |\n`;
+        markdown += `| **受影响版本** | ${vuln.range || "未知"} |\n`;
+
+        // 修复建议
+        if (vuln.fixAvailable) {
+          if (vuln.fixAvailable === false) {
+            markdown += `| **修复建议** | 暂无可用修复 |\n`;
+          } else {
+            markdown += `| **修复建议** | 升级到 ${vuln.fixAvailable.version || "最新版本"} |\n`;
+          }
+        } else {
+          markdown += `| **修复建议** | 检查更新 |\n`;
+        }
+        markdown += `\n`;
+
+        // 漏洞详情
+        if (vuln.via && Array.isArray(vuln.via)) {
+          markdown += `#### 漏洞详情\n`;
+          vuln.via.forEach((issue, index) => {
+            if (typeof issue === "string") {
+              markdown += `${index + 1}. **间接漏洞**: ${issue}\n`;
+            } else {
+              markdown += `${index + 1}. **${issue.title || "未知漏洞"}**\n`;
+              markdown += `   - **严重级别**: ${issue.severity || "未知"}\n`;
+              if (issue.url) {
+                markdown += `   - **参考链接**: [${issue.url}](${issue.url})\n`;
+              }
+              if (issue.range) {
+                markdown += `   - **受影响版本**: ${issue.range}\n`;
+              }
+              if (issue.cvss && issue.cvss.score !== undefined) {
+                markdown += `   - **CVSS 评分**: ${issue.cvss.score}\n`;
+              }
+              if (issue.cwe && issue.cwe.length > 0) {
+                markdown += `   - **CWE**: ${issue.cwe.join(", ")}\n`;
+              }
+            }
+            markdown += `\n`;
+          });
+        }
+        markdown += `---\n\n`;
+      });
+    } else {
+      markdown += `## 详细漏洞列表\n\n`;
+      markdown += `✅ **恭喜！未发现任何安全漏洞。**\n\n`;
+    }
+
+    // 修复建议总结
+    markdown += `## 修复建议总结\n\n`;
+    const vulnerabilitiesObj = auditData.vulnerabilities || {};
+    const hasFixAvailable = Object.values(vulnerabilitiesObj).some(
+      (vuln) => vuln.fixAvailable && vuln.fixAvailable !== false,
+    );
+
+    if (hasFixAvailable) {
+      markdown += `以下依赖有可用修复：\n\n`;
+      Object.entries(vulnerabilitiesObj).forEach(([pkgName, vuln]) => {
+        if (vuln.fixAvailable && vuln.fixAvailable !== false) {
+          const fixVersion = vuln.fixAvailable.version || "最新版本";
+          markdown += `- **${pkgName}**: 升级到版本 ${fixVersion}\n`;
+        }
+      });
+      markdown += `\n`;
+      markdown += `**执行以下命令修复漏洞：**\n\n`;
+      markdown += "```bash\n";
+      Object.entries(vulnerabilitiesObj).forEach(([pkgName, vuln]) => {
+        if (
+          vuln.fixAvailable &&
+          vuln.fixAvailable !== false &&
+          vuln.fixAvailable.name
+        ) {
+          const fixVersion = vuln.fixAvailable.version || "latest";
+          markdown += `npm install ${vuln.fixAvailable.name}@${fixVersion}\n`;
+        }
+      });
+      markdown += "```\n\n";
+    } else if (Object.keys(vulnerabilitiesObj).length > 0) {
+      markdown += `⚠️ **注意**: 发现漏洞但暂无直接修复方案，请考虑以下替代方案：\n`;
+      markdown += `1. 查看是否有可用的次要版本更新\n`;
+      markdown += `2. 考虑使用替代包\n`;
+      markdown += `3. 评估风险是否可接受\n\n`;
+    } else {
+      markdown += `✅ **无需修复** - 项目目前没有安全漏洞。\n\n`;
+    }
+
+    // 结尾
+    markdown += `## 报告说明\n`;
+    markdown += `- 本报告基于 \`npm audit --json\` 命令生成\n`;
+    markdown += `- CVSS (Common Vulnerability Scoring System) 分数范围 0-10，分数越高风险越大\n`;
+    markdown += `- 建议定期运行 \`npm audit\` 检查项目安全状况\n`;
+    markdown += `- 更多信息请参考 [npm 安全文档](https://docs.npmjs.com/auditing-package-dependencies-for-security-vulnerabilities)\n\n`;
+
+    // 将生成的 auditResultMd 转换成md 文件格式 文件放在根目录下
+    await fs.promises.writeFile(savePath, markdown);
+  } catch (error) {
+    console.error(`Error rendering audit result: ${error.message}`);
+    return `# NPM Audit 报告渲染错误\n\n❌ **错误**: ${error.message}\n\n**原始结果**:\n\n\`\`\`json\n${auditResult.substring(0, 1000)}\n\`\`\``;
+  }
+}