@hhxhhxhhx/hhx-mcp-audit 1.0.0

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@hhxhhxhhx/hhx-mcp-audit",
+  "version": "1.0.0",
+  "description": "",
+  "main": "src/mcpServer.js",
+  "type": "module",
+  "scripts": {
+    "start": "node src/mcpServer.js"
+  },
+  "keywords": [],
+  "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/common/utils.js

@@ -0,0 +1,35 @@
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec); // 将 exec 转换为返回 Promise 的函数
+
+export async function runCommand(cmd, cwd) {
+  try {
+    const stdout = await execAsync(cmd, {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // 返回 audit 的 JSON 结果
+    return stdout.stdout.toString();
+  } catch (err) {
+    if (err.stdout) {
+      return err.stdout.toString();
+    }
+    throw err;
+  }
+}
+
+export function uniqueId() {
+  return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+}
+
+export function getFilename(importMetaUrl) {
+  return fileURLToPath(importMetaUrl);
+}
+
+export function getDirname(importMetaUrl) {
+  return dirname(getFilename(importMetaUrl));
+}

package/src/entry/index.js

@@ -0,0 +1,28 @@
+import { createWorkDir, deleteWorkDir } from '../workDir/index.js';
+import { parseProject } from '../parseProject/index.js';
+import { generateLock } from '../generateLock/index.js';
+import { audit } from '../audit/index.js';
+import { render } from '../render/index.js';
+import fs from 'fs';
+
+/**
+ * 根据项目根目录，审计项目中所有的包（含项目本身）
+ * @param {string} projectRoot 项目根目录，可以是本地目录的绝对路径，也可以是远程仓库的URL
+ * @param {string} savePath 保存审计结果的文件名，审计结果是一个标准格式的markdown字符串
+ */
+export async function auditPackage(projectRoot, savePath) {
+  // 1. 创建工作目录
+  const workDir = await createWorkDir();
+  // 2. 解析项目，向工作目录添加pacakge.json
+  const packageJson = await parseProject(projectRoot);
+  // // 3. 生成lock文件
+  await generateLock(workDir, packageJson);
+  // // 4. 对工作目录进行审计
+  const auditResult = await audit(workDir, packageJson);
+  // // 5. 渲染审计结果
+  const renderedResult = await render(auditResult, packageJson);
+  // // 6. 删除工作目录
+  await deleteWorkDir(workDir);
+  // // 7. 将结果保存到指定路径
+  await fs.promises.writeFile(savePath, renderedResult);
+}

package/src/generateLock/generateLock.js

@@ -0,0 +1,27 @@
+import fs from 'fs';
+import { join, dirname } from 'path';
+import { runCommand } from '../common/utils.js';
+
+// 写入 package.json
+async function writePackageJson(workDir, packageJson) {
+  const packageJsonPath = join(workDir, 'package.json');
+  fs.mkdirSync(dirname(packageJsonPath), { recursive: true });
+  await fs.promises.writeFile(
+    packageJsonPath,
+    JSON.stringify(packageJson),
+    'utf8'
+  );
+}
+
+// 创建 lock 文件
+async function createLockFile(workDir) {
+  const cmd = `npm install --package-lock-only --force`;
+  await runCommand(cmd, workDir); // 在工作目录中执行命令
+}
+
+export async function generateLock(workDir, packageJson) {
+  // 1. 将 package.json 写入工作目录
+  await writePackageJson(workDir, packageJson);
+  // 2. 生成 lock 文件
+  await createLockFile(workDir);
+}

package/src/generateLock/index.js

@@ -0,0 +1 @@
+export { generateLock } from './generateLock.js';

package/src/main/index.js

@@ -0,0 +1,23 @@
+import { createWorkDir, deleteWorkDir } from '../workDir/index.js';
+import { parseProject } from '../parseProject/index.js';
+
+/**
+ * 对项目本身以及其所有直接和间接依赖进行安全审计
+ * @param {string} projectRoot 项目根目录，可以是本地项目的路径或远程项目的URL
+ */
+export async function auditProject(projectRoot) {
+  // 1. 创建工作目录
+  const workDir = await createWorkDir();
+  // 2. 解析项目的package.json文件
+  const packageJSON = await parseProject(projectRoot);
+  // 3. 在工作目录中写入
+  const depTree = await generateDepTree(packageJSON);
+  // 3. 解析依赖树，获取每个包的依赖关系
+  const parsedTree = await parseTree(depTree);
+  // 4. 创建审计任务
+  const tasks = createTasks(parsedTree);
+}
+
+auditProject(
+  '/Users/yuanjin/工作/课/录播课/付费课/60 天任务式学习/08. vue从入门到实战/案例/my-site'
+);

package/src/mcpServer.js

@@ -0,0 +1,56 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { auditPackage } from './entry/index.js';
+
+const server = new McpServer({
+  name: 'audit-server',
+  title: '前端工程安全审计服务',
+  version: '0.1.0',
+});
+
+server.registerTool(
+  'auditPackage',
+  {
+    title: '审计前端工程',
+    description:
+      '审计前端工程的所有直接和间接依赖，得到安全审计结果。支持本地工程的审计，也支持远程仓库的审计。审计结果为标准格式的markdown字符串，不用修改，直接用于展示即可。',
+    inputSchema: {
+      projectRoot: z
+        .string()
+        .describe('本地工程的根路径，或者远程仓库的URL地址'),
+      savePath: z
+        .string()
+        .describe(
+          '保存审计结果的路径，传递当前工程的根路径下的工程明audit.md，如果没有当前工程，则传递桌面路径下的audit.md（注意，桌面路径必须传入绝对路径）'
+        ),
+    },
+  },
+  async ({ projectRoot, savePath }) => {
+    try {
+      await auditPackage(projectRoot, savePath);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `审计完成，结果已保存到: ${savePath}`,
+          },
+        ],
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `审计失败: ${message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/parseProject/index.js

@@ -0,0 +1,18 @@
+import { parseLocalProject } from './parseLocalProject.js';
+import { parseRemoteProject } from './parseRemoteProject.js';
+
+/**
+ * 解析工程根目录下的package.json文件
+ * @param {string} projectRoot 工程本地的根目录或远程仓库的URL
+ * @example
+ * parseProject('/path/to/local/project');
+ * parseProject('https://github.com/webpack/webpack');
+ * @returns {Promise<Object>} 返回解析后的package.json内容
+ * @throws {Error} 如果解析失败或文件不存在
+ */
+export function parseProject(projectRoot) {
+  if (projectRoot.startsWith('http://') || projectRoot.startsWith('https://')) {
+    return parseRemoteProject(projectRoot);
+  }
+  return parseLocalProject(projectRoot);
+}

package/src/parseProject/parseLocalProject.js

@@ -0,0 +1,8 @@
+import path from 'path';
+import fs from 'fs';
+
+export async function parseLocalProject(projectRoot) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  const json = await fs.promises.readFile(packageJsonPath, 'utf8');
+  return JSON.parse(json);
+}

package/src/parseProject/parseRemoteProject.js

@@ -0,0 +1,65 @@
+/**
+ * 解析 GitHub 仓库 URL，提取 owner、repo 和后续路径
+ * 支持格式：
+ *   - https://github.com/owner/repo
+ *   - https://github.com/owner/repo/tree/branch
+ *   - https://github.com/owner/repo/blame/...
+ *   等等
+ *
+ * @param {string} url - GitHub 仓库 URL
+ * @returns {Object} { owner, repo, path }
+ * @throws {Error} 如果 URL 格式不合法或无法解析
+ */
+function parseGithubUrl(url) {
+  try {
+    const parsedUrl = new URL(url);
+
+    // 确保是 github.com
+    if (parsedUrl.hostname !== 'github.com') {
+      throw new Error('Only github.com URLs are supported');
+    }
+
+    // 获取路径并去除空字符串（如开头的 /）
+    const parts = parsedUrl.pathname.split('/').filter(Boolean);
+
+    // 至少需要 owner 和 repo 两段
+    if (parts.length < 2) {
+      throw new Error(
+        'Invalid GitHub repository URL: insufficient path segments'
+      );
+    }
+
+    const owner = parts[0];
+    const repo = parts[1];
+    const restPath = parts.slice(2); // 剩余路径，如 ['tree', 'v5.2.2']
+
+    // 构造 path：如果有后续路径，则以 '/' 开头拼接；否则为空字符串
+    const path = restPath.length > 0 ? '/' + restPath.join('/') : '';
+
+    return { owner, repo, path };
+  } catch (error) {
+    if (error instanceof TypeError) {
+      throw new Error('Invalid URL: malformed or missing');
+    }
+    throw error;
+  }
+}
+
+async function getPackageJsonUrl(gitInfo) {
+  let { owner, repo, path } = gitInfo;
+  if (path.startsWith('/tree/')) {
+    const pathParts = path.split('/').filter(Boolean);
+    path = `tags/${pathParts[1]}`;
+  } else {
+    const url = `https://api.github.com/repos/${owner}/${repo}`;
+    const info = await fetch(url).then((resp) => resp.json());
+    path = `heads/${info.default_branch}`;
+  }
+  return `https://raw.githubusercontent.com/${owner}/${repo}/${path}/package.json`;
+}
+
+export async function parseRemoteProject(githubUrl) {
+  const gitInfo = parseGithubUrl(githubUrl);
+  const packgeJsonUrl = await getPackageJsonUrl(gitInfo);
+  return await fetch(packgeJsonUrl).then((resp) => resp.json());
+}

package/src/render/index.js

@@ -0,0 +1,24 @@
+import { renderMarkdown } from './markdown.js';
+
+const desc = {
+  severityLevels: {
+    low: '低危',
+    moderate: '中危',
+    high: '高危',
+    critical: '严重',
+  },
+};
+
+/**
+ * 讲auditResult渲染为markdown格式的字符串
+ * @param {object} auditResult 规范化的审计结果
+ * @param {object} packageJson 包的package.json内容
+ */
+export async function render(auditResult, packageJson) {
+  const data = {
+    audit: auditResult,
+    desc,
+    packageJson,
+  };
+  return await renderMarkdown(data);
+}

package/src/render/markdown.js

@@ -0,0 +1,17 @@
+import ejs from 'ejs';
+import { join } from 'path';
+import { getDirname } from '../common/utils.js';
+
+const templatePath = join(getDirname(import.meta.url), './template/index.ejs');
+
+export function renderMarkdown(data) {
+  return new Promise((resolve, reject) => {
+    ejs.renderFile(templatePath, data, (err, str) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve(str);
+    });
+  });
+}

package/src/render/template/audit.ejs

@@ -0,0 +1,30 @@
+您所审计的工程总共有 **<%- audit.summary.total %>** 个风险漏洞。
+
+其中：
+
+- **<%- desc.severityLevels.critical %>漏洞**：共计 **<%- audit.summary.critical %>** 个
+- **<%- desc.severityLevels.high %>漏洞**：共计 **<%- audit.summary.high %>** 个
+- **<%- desc.severityLevels.moderate %>漏洞**：共计 **<%- audit.summary.moderate %>** 个
+- **<%- desc.severityLevels.low %>漏洞**：共计 **<%- audit.summary.low %>** 个
+
+> 说明：
+>
+> - **<%- desc.severityLevels.critical %>**漏洞被认为是极其严重的，应该立即修复。
+> - **<%- desc.severityLevels.high %>**漏洞被认为是严重的，应该尽快修复。
+> - **<%- desc.severityLevels.moderate %>**漏洞被认为是中等严重的，可以选择在时间允许时修复。
+> - **<%- desc.severityLevels.low %>**漏洞被认为是轻微的，可以根据自行需要进行修复。
+
+下面是漏洞的详细信息
+
+<% if (audit.summary.critical) { %>
+<%- include('./detail.ejs', {type:'critical'}); %>
+<% } %>
+<% if (audit.summary.high) { %>
+<%- include('./detail.ejs', {type:'high'}); %>
+<% } %>
+<% if (audit.summary.moderate) { %>
+<%- include('./detail.ejs', {type:'moderate'}); %>
+<% } %>
+<% if (audit.summary.low) { %>
+<%- include('./detail.ejs', {type:'low'}); %> 
+<% } %>

package/src/render/template/detail-item.ejs

@@ -0,0 +1,32 @@
+### `<%- item.name -%>`
+
+**漏洞描述**：
+<% item.problems.forEach((problem) => { %>
+- <%- problem.title %>
+  - npm漏洞编号：`<%- problem.source %>`
+  - 漏洞详细说明：<%- problem.url %>
+  - 漏洞等级：<%- desc.severityLevels[problem.severity] %>
+  - 受影响的版本：`<%- problem.range %>`
+<% }); %>
+
+**依赖关系**：
+<% if(item.depChains.length === 0) { %>
+<% if(item.name === packageJson.name) { %>
+当前工程
+<% } else { %>
+- `<%- packageJson.name %>` / <%- item.name %>
+<% } %>
+<% } else { %>
+<% item.depChains.forEach((chain) => { %>
+<% if(chain.length === 1 && chain[0] === packageJson.name) { %>
+当前工程
+<% } else { %>
+- `<%- packageJson.name %>` / <%- chain.map(c=>`\`${c}\``).join(' / ') %>
+<% } %>
+  <% }); %>
+  <% } %>
+
+**漏洞包所在目录**：
+<% item.nodes.forEach((path) => { %>
+- `<%- path %>`
+<% }); %>

package/src/render/template/detail.ejs

@@ -0,0 +1,7 @@
+## <%-desc.severityLevels[type] %>漏洞
+
+共计 **<%- audit.summary[type] %>** 个
+
+<% audit.vulnerabilities[type].forEach(function(item){ %>
+<%- include('./detail-item.ejs', {item: item}) %>
+<% }); %>

package/src/render/template/index.ejs

@@ -0,0 +1,8 @@
+# `<%- packageJson.name %>`审计结果
+
+<% if(audit.summary.total) { %>
+<%- include('./audit.ejs'); %>
+<% } %>
+<% if(audit.summary.total === 0) { %>
+你项目的所有直接依赖和间接依赖都没有发现任何风险漏洞。
+<% } %>

package/src/workDir/index.js

@@ -0,0 +1,21 @@
+import fs from 'fs';
+
+import { join } from 'path';
+import { uniqueId, getDirname } from '../common/utils.js';
+
+const __dirname = getDirname(import.meta.url); // 获取当前文件的目录名
+
+const basePath = join(__dirname, '../..'); // 获取上两级目录
+const workBasePath = join(basePath, 'work'); // 定义工作目录路径
+fs.mkdirSync(workBasePath, { recursive: true }); // 确保工作目录存在
+
+export async function createWorkDir() {
+  const workDir = join(workBasePath, uniqueId());
+  await fs.promises.mkdir(workDir, { recursive: true }); // 创建工作目录
+  return workDir;
+}
+
+// 删除工作目录
+export async function deleteWorkDir(workDir) {
+  await fs.promises.rm(workDir, { recursive: true }); // 删除工作目录
+}