@anren-utils/mcp-audit 1.0.0

package/src/types.ts

@@ -0,0 +1,429 @@
+export interface PackageJsonInfo {
+  name: string;
+  version: string;
+  workspaces?: [];
+  [x: string]: any;
+}
+
+/** 包管理器类型 */
+export type PackageManager = "npm" | "pnpm" | "yarn";
+
+export type AuditSeverity =
+  | "low" // 低危
+  | "moderate" // 中危
+  | "high" // 高危
+  | "critical" // 严重
+  | "info"; // 信息级
+
+/**
+ * 表示漏洞来源的详细对象
+ * 当 npm audit 输出详细信息时，via 字段会包含此类对象的数组
+ */
+export interface VulnerabilitySourceDetail {
+  /**
+   * 漏洞在 npm 安全数据库中的唯一 ID
+   * 通常是一个数字，例如 1089234
+   */
+  source: number;
+
+  /**
+   * 存在漏洞的包名
+   * 这是真正引入安全问题的那个具体的包
+   */
+  name: string;
+
+  /**
+   * 依赖名称
+   * 通常与 name 相同，指代有问题的依赖项
+   */
+  dependency: string;
+
+  /**
+   * 漏洞的标题
+   * 简要描述漏洞的类型，例如 "Prototype Pollution in minimist"
+   */
+  title: string;
+
+  /**
+   * 漏洞详情的 URL
+   * 链接到 npm advisory 或 GitHub advisory 的详细报告页面
+   */
+  url: string;
+
+  /**
+   * 漏洞的严重程度
+   * 可选值: 'info' | 'low' | 'moderate' | 'high' | 'critical'
+   */
+  severity: AuditSeverity;
+
+  /**
+   * 受影响的版本范围
+   * 使用 semver 语法描述哪些版本是脆弱的
+   * 例如: "<1.2.6" 表示小于 1.2.6 的所有版本
+   * 例如: ">=4.0.0 <4.1.5" 表示 4.0.0 到 4.1.5 之间的版本
+   */
+  range: string;
+
+  /**
+   * (可选) 漏洞的简要描述
+   * 某些版本的 npm audit 输出可能包含此字段
+   */
+  overview?: string;
+
+  /**
+   * (可选) 修复建议
+   * 某些版本的 npm audit 输出可能包含此字段，通常建议升级到特定版本
+   */
+  recommendation?: string;
+}
+
+export interface VulnerabilityInfo {
+  /** 包的名称 */
+  packageName: string;
+  name: string;
+  /** 是否是工程直接依赖 */
+  isDirect: boolean;
+  /** 漏洞级别，取所有子依赖中漏洞级别的最高级 */
+  severity: AuditSeverity;
+  /**
+   * 漏洞的来源或传播路径
+   * @description 如果是字符串，表示是因为包的子依赖有漏洞导致的包本身产生了漏洞（字符串就是子依赖的名称）；如果是对象，表示是因为包自身有漏洞导致的包本身产生了漏洞（字符串就是子依赖的名称）。如果是对象，则表示包自身有漏洞
+   */
+  via: Array<string | VulnerabilitySourceDetail>;
+  /**
+   * 漏洞的影响范围
+   * @description 表示包自身的漏洞影响了哪些包，即：哪些包用到了自己
+   */
+  effects: string[];
+  /** 包的位置路径 */
+  nodes: string[];
+  /** 包的版本范围 */
+  range: string;
+}
+
+export interface AuditMetadata {
+  /**
+   * 漏洞统计信息
+   * 按照严重程度分类的漏洞数量
+   */
+  vulnerabilities: {
+    /**
+     * 信息级别漏洞
+     * 通常无害，仅提供信息
+     */
+    info: number;
+    /**
+     * 低危漏洞
+     * 风险极低，利用难度大
+     */
+    low: number;
+    /**
+     * 中危漏洞
+     * 有一定风险，需关注
+     */
+    moderate: number;
+    /**
+     * 高危漏洞
+     * 可能导致数据泄露或服务中断，建议尽快修复
+     */
+    high: number;
+    /**
+     * 严重漏洞
+     * 最高优先级，可能导致远程代码执行等严重后果
+     */
+    critical: number;
+    /**
+     * 漏洞总数
+     */
+    total: number;
+  };
+  /**
+   * 依赖包统计信息
+   * 按照依赖类型分类的包数量（注意：这里通常是包的数量，而非漏洞数量）
+   */
+  dependencies: {
+    /**
+     * 生产环境依赖
+     * 最终打包上线所需的依赖包数量
+     */
+    prod: number;
+    /**
+     * 开发环境依赖
+     * 仅在开发阶段（如构建、测试、Lint）使用的依赖包数量
+     */
+    dev: number;
+    /**
+     * 可选依赖
+     * 安装时标记为 --optional 的依赖包数量
+     */
+    optional: number;
+    /**
+     * 同伴依赖
+     * 要求宿主环境必须提供的依赖包数量
+     */
+    peer: number;
+    /**
+     * 可选同伴依赖
+     */
+    peerOptional: number;
+    /**
+     * 依赖包总数
+     */
+    total: number;
+  };
+}
+
+export interface AuditResult {
+  /** 审计报告的版本号 */
+  auditReportVersion: number;
+  /** 所有被发现有漏洞的具体包相关信息 */
+  vulnerabilities: Record<string, VulnerabilityInfo>;
+  /** 关于漏洞严重程度和依赖数量的统计信息 */
+  metadata: AuditMetadata;
+}
+
+/**
+ * 标准化后的漏洞信息对象
+ */
+export interface NormalizedVulnerabilityInfo {
+  /**
+   * 存在漏洞的包名
+   */
+  name: string;
+
+  /**
+   * 漏洞的严重程度
+   */
+  severity: AuditSeverity;
+
+  /**
+   * 有效的漏洞来源列表
+   * 经过筛选，仅保留对象类型的 via 信息
+   */
+  problems: VulnerabilitySourceDetail[];
+
+  /**
+   * 受影响的节点 ID 列表
+   * 通常对应 package-lock.json 中的具体位置
+   */
+  nodes: string[];
+
+  /**
+   * 依赖链列表
+   * 描述了该有漏洞的包的所有依赖路径（被哪些包依赖了该包）
+   * 示例结构是: string[][] (如 [["project", "parent", "child"]])
+   * 表示child有漏洞，parent依赖了child，project依赖了parent
+   */
+  depChains?: any[]; // 建议根据 getDepChains 的实际返回值替换 any，例如 string[][] 或 DepNode[][]
+}
+
+/**
+ * npm security audit 完整响应结构
+ */
+export interface NpmAuditResponse {
+  /**
+   * 建议执行的操作列表，用于修复漏洞
+   */
+  actions: AuditAction[];
+
+  /**
+   * 漏洞详情字典，键为 Advisory ID
+   * 包含漏洞的完整元数据（标题、概述、CVSS评分等）
+   */
+  advisories: Record<number, Advisory>;
+
+  /**
+   * 用户选择忽略（静音）的漏洞列表
+   */
+  muted: MutedItem[];
+
+  /**
+   * 审计元数据，包含统计信息
+   */
+  metadata: AuditMetadata;
+}
+
+/**
+ * 建议的修复操作
+ */
+export interface AuditAction {
+  /**
+   * 操作类型，通常是 'install' 或 'update'
+   */
+  action: "install" | "update" | "review";
+
+  /**
+   * 涉及的模块名，通常包含版本号，如 "lodash@4.17.21"
+   */
+  module: string;
+
+  /**
+   * 该操作能解决的漏洞路径列表
+   */
+  resolves: AuditResolve[];
+}
+
+/**
+ * 操作能解决的漏洞详情
+ */
+export interface AuditResolve {
+  /**
+   * 漏洞的 Advisory ID
+   */
+  id: number;
+
+  /**
+   * 漏洞在依赖树中的路径，用 ">" 分隔
+   */
+  path: string;
+
+  /**
+   * 是否是开发依赖
+   */
+  dev: boolean;
+
+  /**
+   * 是否是可选依赖
+   */
+  optional: boolean;
+
+  /**
+   * 是否是打包依赖
+   */
+  bundled: boolean;
+}
+
+/**
+ * 漏洞的完整详情
+ */
+export interface Advisory {
+  /**
+   * 漏洞 ID
+   */
+  id: number;
+
+  /**
+   * 漏洞详情页 URL
+   */
+  url: string;
+
+  /**
+   * 漏洞标题
+   */
+  title: string;
+
+  /**
+   * 严重程度: low, moderate, high, critical
+   */
+  severity: AuditSeverity;
+
+  /**
+   * 通用弱点枚举代码
+   */
+  cwe: string[];
+
+  /**
+   * 通用漏洞评分系统数据
+   */
+  cvss: CvssData;
+
+  /**
+   * 发现者信息
+   */
+  found_by: ReporterInfo;
+
+  /**
+   * 报告者信息
+   */
+  reported_by: ReporterInfo;
+
+  /**
+   * 受影响的模块名称
+   */
+  module_name: string;
+
+  /**
+   * 漏洞发布时间
+   */
+  publish_date: string;
+
+  /**
+   * 漏洞更新时间
+   */
+  updated_date: string;
+
+  /**
+   * 漏洞概述
+   */
+  overview: string;
+
+  /**
+   * 修复建议
+   */
+  recommendation: string;
+
+  /**
+   * 参考链接
+   */
+  references: string[];
+
+  /**
+   * 是否通过其他包间接访问
+   */
+  accessed_via_other_package: boolean;
+
+  /**
+   * 受影响的版本范围
+   */
+  vulnerable_versions: string;
+
+  /**
+   * 已修复的版本范围
+   */
+  patched_versions: string;
+}
+
+/**
+ * CVSS 评分数据
+ */
+export interface CvssData {
+  /**
+   * 评分分数
+   */
+  score: number;
+
+  /**
+   * 向量字符串
+   */
+  vectorString: string;
+}
+
+/**
+ * 报告者/发现者信息
+ */
+export interface ReporterInfo {
+  /**
+   * 链接
+   */
+  link: string;
+
+  /**
+   * 名称
+   */
+  name: string;
+}
+
+/**
+ * 被静音的漏洞项
+ */
+export interface MutedItem {
+  /**
+   * 涉及的包名
+   */
+  name: string;
+
+  /**
+   * 被静音的 Advisory ID 列表
+   */
+  advisories: number[];
+}

package/src/utils/dirUtils.ts

@@ -0,0 +1,31 @@
+import fs from "fs";
+import { join } from "path";
+import { getDirname, uniqueId } from "./index.js";
+
+// 获取当前文件的目录名称
+const __dirname = getDirname(import.meta.url);
+
+// 获取上两级目录（项目根目录）
+const basepath = join(__dirname, "../..");
+// 定义工作目录路径
+const workBasePath = join(basepath, "work");
+// 确保工作目录存在
+fs.mkdirSync(workBasePath, { recursive: true });
+
+/**
+ * @Desc: 创建工作目录
+ * @return {string} 工作目录路径
+ */
+export async function createWorkDir(workDirPath = workBasePath) {
+  const workDir = join(workDirPath, uniqueId());
+  await fs.promises.mkdir(workDir, { recursive: true });
+  return workDir;
+}
+
+/**
+ * @Desc: 删除工作目录
+ * @param {string} workDir 工作目录路径
+ */
+export async function deleteWorkDir(workDir = workBasePath) {
+  await fs.promises.rm(workDir, { recursive: true, force: true });
+}

package/src/utils/index.ts

@@ -0,0 +1,88 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { exec } from "child_process";
+import { promisify } from "util";
+import type { RemoteProjectUrlInfo } from "../parseProject/parseRemoteProject.js";
+
+const execAsync = promisify(exec);
+
+interface ExecAsyncError extends Error {
+  stdout: string;
+  stderr: string;
+}
+
+/**
+ * @Desc: 执行shell命令
+ * @return {*}
+ * @param {string} cmd 命令
+ * @param {string} cwd 工作目录
+ */
+export async function runCommand(cmd: string, cwd: string) {
+  try {
+    const stdout = await execAsync(cmd, {
+      cwd,
+      // stdio: ["ignore", "pipe", "pipe"],
+    });
+    // 返回 audit 的 JSON 结果
+    return stdout.stdout.toString();
+  } catch (err: unknown) {
+    const error = err as ExecAsyncError;
+    if (error.stdout) {
+      return error.stdout.toString();
+    }
+    throw err;
+  }
+}
+
+/**
+ * @Desc: 生成唯一ID
+ * @return {string} 唯一ID
+ */
+export function uniqueId() {
+  return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+}
+
+/**
+ * @Desc: 获取文件名
+ * @return {string} 文件名
+ * @param {string} importMetaUrl 导入元URL
+ */
+export function getFilename(importMetaUrl: string) {
+  return fileURLToPath(importMetaUrl);
+}
+
+/**
+ * @Desc: 获取文件目录
+ * @return {string} 文件目录
+ * @param {string} importMetaUrl 导入元URL
+ */
+export function getDirname(importMetaUrl: string) {
+  return dirname(getFilename(importMetaUrl));
+}
+
+/**
+ * @Desc: 根据不同的平台类型，得到获取文件内容的链接
+ * @param {RemoteProjectUrlInfo} gitInfo 仓库URL信息
+ * @param {string} branchName 分支名称
+ * @param {string} path 文件路径
+ * @return {string} 获取文件内容的链接
+ */
+export function getReadFileUrl(
+  gitInfo: RemoteProjectUrlInfo,
+  branchName: string,
+  path: string,
+) {
+  const { owner, repo, platform } = gitInfo;
+  switch (platform) {
+    case "github":
+      return `https://raw.githubusercontent.com/${owner}/${repo}/${branchName}/${path}`;
+    case "gitee":
+      // return `https://raw.gitee.com/${owner}/${repo}/${branchName}/${path}`;
+      return `https://gitee.com/${owner}/${repo}/raw/${branchName}/${path}`;
+    case "gitlab":
+      // return `https://rawlab.com/${owner}/${repo}/${branchName}/${path}`;
+      return `https://gitlab.com/${owner}/${repo}/-/raw/${branchName}/${path}`;
+    default:
+      throw new Error(`Unsupported platform: ${platform}`);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    "rootDir": "./src",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    // For nodejs:
+    "lib": ["esnext"],
+    "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}