mcp-audit-server 1.0.0

package/PUBLISH_GUIDE.md

@@ -0,0 +1,67 @@
+# npm 发布指南：解决双因素认证问题
+
+## 问题描述
+
+在执行 `npm publish --access public` 时遇到以下错误：
+
+```
+npm error 403 403 Forbidden - PUT https://registry.npmjs.org/mcp-audit - Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages.
+```
+
+## 解决方案：创建细粒度访问令牌
+
+### 步骤 1：登录 npm 账户
+
+访问 [npm 官网](https://www.npmjs.com/) 并登录您的账户。
+
+### 步骤 2：进入访问令牌设置
+
+1. 点击右上角的用户头像，选择 "Account"
+2. 在左侧导航栏中选择 "Access Tokens"
+3. 点击 "Generate New Token" 按钮，选择 "Granular Access Token"
+
+### 步骤 3：配置令牌权限
+
+1. **Token Name**：输入一个描述性名称，例如 "mcp-audit-publish"
+2. **Expiration**：选择合适的过期时间
+3. **Package Access**：
+   - 选择 "Read and Write"
+   - 在 "Packages" 部分，选择 "All packages in your account"
+4. **Enable "Bypass 2FA"**：确保勾选此选项
+
+### 步骤 4：生成并保存令牌
+
+1. 点击 "Generate Token" 按钮
+2. **重要**：复制生成的令牌，因为它只会显示一次
+3. 保存令牌到安全的地方
+
+### 步骤 5：使用新令牌发布
+
+在终端中执行以下命令：
+
+```bash
+# 方法 1：直接在命令中使用令牌
+npm publish --access public --registry=https://registry.npmjs.org/ --//registry.npmjs.org/:_authToken=<YOUR_TOKEN>
+
+# 方法 2：更新 npm 配置
+npm config set //registry.npmjs.org/:_authToken <YOUR_TOKEN>
+npm publish --access public
+```
+
+## 替代方案：启用双因素认证
+
+如果您更倾向于使用双因素认证，可以：
+
+1. 在 npm 账户设置中启用双因素认证
+2. 使用 `npm publish --access public --otp` 命令
+3. 当提示输入验证码时，输入您的认证应用生成的代码
+
+## 注意事项
+
+- 细粒度访问令牌具有更高的安全性，因为您可以精确控制其权限范围
+- 请确保保护好您的访问令牌，不要在代码或公开场合中泄露
+- 如果令牌泄露，请立即在 npm 账户中撤销它
+
+## 验证发布
+
+发布成功后，您可以在 [npm 官网](https://www.npmjs.com/) 上查看您的包是否已成功发布。

package/bin/cli.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+// CLI 入口：通过 npx 或全局安装启动 MCP 服务
+import '../src/mcpServer.js';
+

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "mcp-audit-server",
+  "version": "1.0.0",
+  "description": "前端工程依赖安全审计的 MCP 服务",
+  "main": "src/main/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-audit-server": "bin/cli.js"
+  },
+  "scripts": {
+    "start": "node bin/cli.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "mcp",
+    "audit",
+    "security"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.1",
+    "ejs": "^3.1.10",
+    "zod": "^3.25.76"
+  }
+}

package/src/audit/currentAudit.js

@@ -0,0 +1,50 @@
+import { remoteAudit } from './remoteAudit.js';
+const severityLevelsMap = {
+  info: 0,
+  low: 1,
+  moderate: 2,
+  high: 3,
+  critical: 4,
+};
+
+// 添加当前工程的审计结果
+export async function currentAudit(name, version) {
+  // 1. 调用 remoteAudit 函数获取审计结果
+  const auditResult = await remoteAudit(name, version);
+
+  // 2. 规格化审计结果
+  if (
+    !auditResult.advisories ||
+    Object.keys(auditResult.advisories).length === 0
+  ) {
+    return null;
+  }
+  const result = {
+    name,
+    range: version,
+    nodes: ['.'],
+    depChains: [],
+  };
+  const advisories = Object.values(auditResult.advisories);
+  let maxSeverity = 'info';
+  result.problems = advisories.map((advisory) => {
+    const problem = {
+      source: advisory.id,
+      name,
+      dependency: name,
+      title: advisory.title,
+      url: advisory.url,
+      severity: advisory.severity,
+      cwe: advisory.cwe,
+      cvss: advisory.cvss,
+      range: advisory.vulnerable_versions,
+    };
+    // 更新最大严重性
+    if (severityLevelsMap[problem.severity] > severityLevelsMap[maxSeverity]) {
+      maxSeverity = problem.severity;
+    }
+    return problem;
+  });
+  result.severity = maxSeverity;
+  return result;
+}

package/src/audit/getDepChain.js

@@ -0,0 +1,47 @@
+/**
+ * 给定图结构中的一个节点，获取从该节点的依赖节点出发一直走到终点，一共走出的所有链条
+ * 注意：图结构中可能存在环，遇到环时，环所在的节点直接作为终点即可
+ * @param {Node} node
+ * @returns {Array<Set<string>>} 返回所有依赖链，每个链是一个字符串集合，每个字符串是一个节点名称
+ */
+export function getDepChains(node, globalNodeMap) {
+  // 存储所有找到的依赖链
+  const chains = [];
+
+  // 当前DFS路径（用于检测环）
+  const currentPath = [];
+
+  /**
+   * 深度优先搜索函数
+   * @param {Node} currentNode - 当前处理的节点
+   */
+  function dfs(currentNode) {
+    if (!currentNode) return;
+
+    // 检查是否形成环（当前节点已在路径中）
+    if (currentPath.includes(currentNode.name)) {
+      chains.push([...currentPath]);
+      return;
+    }
+
+    // 将当前节点加入路径
+    currentPath.unshift(currentNode.name);
+
+    // 如果没有依赖节点，说明到达终点
+    if (!currentNode.effects || currentNode.effects.length === 0) {
+      chains.push([...currentPath]);
+    } else {
+      // 递归处理所有依赖节点
+      for (const effect of currentNode.effects) {
+        dfs(globalNodeMap[effect]);
+      }
+    }
+    // 回溯：移除当前节点
+    currentPath.shift();
+  }
+
+  // 从给定节点开始DFS
+  dfs(node);
+
+  return chains;
+}

package/src/audit/index.js

@@ -0,0 +1,28 @@
+import { npmAudit } from './npmAudit.js';
+import { normalizeAuditResult } from './normalizeAuditResult.js';
+import { currentAudit } from './currentAudit.js';
+
+export async function audit(workDir, packageJson) {
+  // 调用 npmAudit 获取审计结果
+  const auditResult = await npmAudit(workDir);
+  // 规范化审计结果
+  const normalizedResult = normalizeAuditResult(auditResult);
+
+  // 添加当前工程的审计结果
+  const current = await currentAudit(packageJson.name, packageJson.version);
+  if (current) {
+    normalizedResult.vulnerabilities[current.severity].unshift(current);
+  }
+  // 添加汇总信息
+  normalizedResult.summary = {
+    total: Object.values(normalizedResult.vulnerabilities).reduce(
+      (sum, arr) => sum + arr.length,
+      0
+    ),
+    critical: normalizedResult.vulnerabilities.critical.length,
+    high: normalizedResult.vulnerabilities.high.length,
+    moderate: normalizedResult.vulnerabilities.moderate.length,
+    low: normalizedResult.vulnerabilities.low.length,
+  };
+  return normalizedResult;
+}

package/src/audit/normalizeAuditResult.js

@@ -0,0 +1,47 @@
+import { getDepChains } from './getDepChain.js';
+
+function _normalizeVulnerabilities(auditResult) {
+  const result = {
+    critical: [],
+    high: [],
+    moderate: [],
+    low: [],
+  };
+  for (const key in auditResult.vulnerabilities) {
+    const packageInfo = auditResult.vulnerabilities[key];
+    const normalizedPackage = _normalizePackage(packageInfo);
+    if (normalizedPackage) {
+      result[normalizedPackage.severity].push(normalizedPackage);
+    }
+  }
+  return result;
+
+  function _normalizePackage(packageInfo) {
+    const { via = [] } = packageInfo;
+    const validVia = via.filter((it) => typeof it === 'object');
+    if (validVia.length === 0) {
+      return null;
+    }
+    const info = {
+      name: packageInfo.name,
+      severity: packageInfo.severity,
+      problems: validVia,
+      nodes: packageInfo.nodes || [],
+    };
+    info.depChains = getDepChains(packageInfo, auditResult.vulnerabilities);
+    // info.depChains = info.depChains.filter(
+    //   (chain) => !isInvalidChain(chain, packageInfo.name)
+    // );
+    return info;
+  }
+}
+
+function isInvalidChain(chain, packageName) {
+  return chain.length === 0 || (chain.length === 1 && chain[0] === packageName);
+}
+
+export function normalizeAuditResult(auditResult) {
+  return {
+    vulnerabilities: _normalizeVulnerabilities(auditResult),
+  };
+}

package/src/audit/npmAudit.js

@@ -0,0 +1,10 @@
+import fs from 'fs';
+import { join } from 'path';
+import { runCommand } from '../common/utils.js';
+
+export async function npmAudit(workDir) {
+  const cmd = `npm audit --json`;
+  const jsonResult = await runCommand(cmd, workDir); // 在工作目录中执行命令
+  const auditData = JSON.parse(jsonResult);
+  return auditData;
+}

package/src/audit/remoteAudit.js

@@ -0,0 +1,24 @@
+const URL = 'https://registry.npmjs.org/-/npm/v1/security/audits';
+
+export async function remoteAudit(packageName, pacakgeVersion) {
+  const body = {
+    name: 'example-audit', // 项目名字随便写
+    version: '1.0.0', // 项目的版本，随便写
+    requires: {
+      [packageName]: pacakgeVersion,
+    },
+    dependencies: {
+      [packageName]: {
+        version: pacakgeVersion,
+      },
+    },
+  };
+  const resp = await fetch(URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  return await resp.json();
+}

package/src/audit/test/test-currentAudit.js

@@ -0,0 +1,15 @@
+import { currentAudit } from '../currentAudit.js';
+import { getDirname } from '../../common/utils.js';
+import { join } from 'path';
+import fs from 'fs';
+
+const workDir = join(getDirname(import.meta.url), './workdir');
+const currentJson = join(workDir, './current.json');
+
+async function test() {
+  const result = await currentAudit('my-site', '0.1.0');
+  fs.writeFileSync(currentJson, JSON.stringify(result, null, 2), 'utf8');
+  console.log('ok');
+}
+
+test();

package/src/audit/test/test-getDepChain.js

@@ -0,0 +1,13 @@
+import { getDepChains } from '../getDepChain.js';
+
+const globalNodeMap = {
+  A: { name: 'A', effects: ['B', 'C'] },
+  B: { name: 'B', effects: ['C'] },
+  C: { name: 'C', effects: ['D'] },
+  D: { name: 'D', effects: ['B', 'E'] }, // recursive dependency
+  E: { name: 'E', effects: [] },
+};
+const nodeA = globalNodeMap['A'];
+
+const chains = getDepChains(nodeA, globalNodeMap);
+console.log(chains); // 输出所有依赖链

package/src/audit/test/test-index.js

@@ -0,0 +1,17 @@
+import { audit } from '../index.js';
+import { getDirname } from '../../common/utils.js';
+import { join } from 'path';
+import fs from 'fs';
+
+const workDir = join(getDirname(import.meta.url), './workdir');
+const indexJson = join(workDir, './index.json');
+const packageJsonPath = join(workDir, 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+async function test() {
+  const result = await audit(workDir, packageJson);
+  fs.writeFileSync(indexJson, JSON.stringify(result, null, 2), 'utf8');
+  console.log('ok');
+}
+
+test();

package/src/audit/test/test-normalizeAuditResult.js

@@ -0,0 +1,18 @@
+import { normalizeAuditResult } from '../normalizeAuditResult.js';
+import fs from 'fs';
+import { join } from 'path';
+import { getDirname } from '../../common/utils.js';
+
+const auditJson = join(getDirname(import.meta.url), './workdir/audit.json');
+const auditResult = JSON.parse(fs.readFileSync(auditJson, 'utf8'));
+function test() {
+  const r = normalizeAuditResult(auditResult);
+  const normalizedPath = join(
+    getDirname(import.meta.url),
+    './workdir/normalized.json'
+  );
+  fs.writeFileSync(normalizedPath, JSON.stringify(r, null, 2), 'utf8');
+  console.log('ok');
+}
+
+test();

package/src/audit/test/test-npmAudit.js

@@ -0,0 +1,15 @@
+import { npmAudit } from '../npmAudit.js';
+import { getDirname } from '../../common/utils.js';
+import { join } from 'path';
+import fs from 'fs';
+
+const workDir = join(getDirname(import.meta.url), './workdir');
+const auditJson = join(workDir, './audit.json');
+
+async function test() {
+  const result = await npmAudit(workDir);
+  fs.writeFileSync(auditJson, JSON.stringify(result, null, 2), 'utf8');
+  console.log('ok');
+}
+
+test();

package/src/audit/test/test-remoteAudit.js

@@ -0,0 +1,15 @@
+import { remoteAudit } from '../remoteAudit.js';
+import { getDirname } from '../../common/utils.js';
+import { join } from 'path';
+import fs from 'fs';
+
+const workDir = join(getDirname(import.meta.url), './workdir');
+const remoteJson = join(workDir, './remote.json');
+
+async function test() {
+  const result = await remoteAudit('ejs', '3.1.9');
+  fs.writeFileSync(remoteJson, JSON.stringify(result, null, 2), 'utf8');
+  console.log('ok');
+}
+
+test();