@pwddd/skills-scanner 2.4.1 → 2026.3.10

package/src/config.ts

@@ -0,0 +1,170 @@
+/**
+ * 配置管理模块
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { ScannerConfig } from "./types.js";
+
+export const skillsScannerConfigSchema: OpenClawPluginConfigSchema = {
+  safeParse: (value: unknown) => {
+    try {
+      const config = value as ScannerConfig;
+      
+      // 验证 policy
+      if (config.policy && !["strict", "balanced", "permissive"].includes(config.policy)) {
+        return {
+          success: false,
+          error: {
+            issues: [{
+              path: ["policy"],
+              message: "policy 必须是 strict、balanced 或 permissive"
+            }]
+          }
+        };
+      }
+      
+      // 验证 preInstallScan
+      if (config.preInstallScan && !["on", "off"].includes(config.preInstallScan)) {
+        return {
+          success: false,
+          error: {
+            issues: [{
+              path: ["preInstallScan"],
+              message: "preInstallScan 必须是 on 或 off"
+            }]
+          }
+        };
+      }
+      
+      // 验证 onUnsafe
+      if (config.onUnsafe && !["quarantine", "delete", "warn"].includes(config.onUnsafe)) {
+        return {
+          success: false,
+          error: {
+            issues: [{
+              path: ["onUnsafe"],
+              message: "onUnsafe 必须是 quarantine、delete 或 warn"
+            }]
+          }
+        };
+      }
+      
+      return { success: true, data: config };
+    } catch (err) {
+      return {
+        success: false,
+        error: {
+          issues: [{
+            path: [],
+            message: String(err)
+          }]
+        }
+      };
+    }
+  },
+  
+  uiHints: {
+    apiUrl: {
+      label: "API 服务地址",
+      help: "扫描 API 服务的 URL 地址",
+      placeholder: "http://localhost:8000"
+    },
+    scanDirs: {
+      label: "扫描目录",
+      help: "要监控的 Skills 目录列表，支持 ~ 路径"
+    },
+    behavioral: {
+      label: "行为分析",
+      help: "启用深度行为分析（较慢但更准确）"
+    },
+    useLLM: {
+      label: "LLM 分析",
+      help: "使用 LLM 进行语义分析"
+    },
+    policy: {
+      label: "扫描策略",
+      help: "strict=严格 / balanced=平衡（推荐）/ permissive=宽松"
+    },
+    preInstallScan: {
+      label: "安装前扫描",
+      help: "监听新 Skill 并自动扫描"
+    },
+    onUnsafe: {
+      label: "不安全处理",
+      help: "quarantine=隔离（推荐）/ delete=删除 / warn=仅警告"
+    }
+  }
+};
+
+export function generateConfigGuide(
+  cfg: ScannerConfig,
+  apiUrl: string,
+  scanDirs: string[],
+  behavioral: boolean,
+  useLLM: boolean,
+  policy: string,
+  preInstallScan: string,
+  onUnsafe: string
+): string {
+  return [
+    "",
+    "╔════════════════════════════════════════════════════════════════╗",
+    "║  🎉 Skills Scanner 首次运行 - 配置向导                         ║",
+    "╚════════════════════════════════════════════════════════════════╝",
+    "",
+    "当前使用默认配置。建议根据您的需求自定义配置：",
+    "",
+    "📋 当前配置：",
+    `  • API 服务地址: ${apiUrl}`,
+    `  • 扫描目录: ${scanDirs.length} 个（自动检测）`,
+    `  • 行为分析: ${behavioral ? "✅ 启用" : "❌ 禁用"}`,
+    `  • LLM 分析: ${useLLM ? "✅ 启用" : "❌ 禁用"}`,
+    `  • 扫描策略: ${policy}`,
+    `  • 安装前扫描: ${preInstallScan === "on" ? "✅ 启用" : "❌ 禁用"}`,
+    `  • 不安全处理: ${onUnsafe}`,
+    "",
+    "🔧 配置文件位置：",
+    "  ~/.openclaw/config.json",
+    "",
+    "📝 推荐配置示例：",
+    "",
+    "```json",
+    "{",
+    '  "plugins": {',
+    '    "entries": {',
+    '      "skills-scanner": {',
+    '        "enabled": true,',
+    '        "config": {',
+    '          "apiUrl": "http://localhost:8000",',
+    '          "scanDirs": ["~/.openclaw/skills"],',
+    '          "behavioral": false,',
+    '          "useLLM": false,',
+    '          "policy": "balanced",',
+    '          "preInstallScan": "on",',
+    '          "onUnsafe": "quarantine"',
+    '        }',
+    '      }',
+    '    }',
+    '  }',
+    "}",
+    "```",
+    "",
+    "💡 配置说明：",
+    "",
+    "1. apiUrl        默认 http://localhost:8000，需先启动 skill-scanner-api 服务",
+    "2. scanDirs      可添加多个目录（默认自动检测 ~/.openclaw/skills）",
+    "3. behavioral    false=快速扫描（推荐），true=深度分析",
+    "4. useLLM        false=不使用 LLM（推荐），true=语义分析",
+    "5. policy        strict / balanced（推荐）/ permissive",
+    "6. preInstallScan on=监听新 Skill 并自动扫描（推荐），off=禁用",
+    "7. onUnsafe      quarantine=隔离（推荐），delete=删除，warn=仅警告",
+    "",
+    "🚀 快速开始：",
+    "  编辑配置文件后重启 Gateway",
+    "  /skills-scanner status",
+    "",
+    "提示：此消息只在首次运行时显示。",
+    "════════════════════════════════════════════════════════════════",
+  ].join("\n");
+}

package/src/cron.ts

@@ -0,0 +1,82 @@
+/**
+ * 定时任务管理模块
+ */
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import type { PluginLogger } from "openclaw/plugin-sdk";
+import { loadState, saveState } from "./state.js";
+
+const execAsync = promisify(exec);
+
+export const CRON_JOB_NAME = "skills-daily-report";
+export const CRON_SCHEDULE = "0 8 * * *";
+export const CRON_TIMEZONE = "Asia/Shanghai";
+
+export async function ensureCronJob(logger: PluginLogger): Promise<void> {
+  const state = loadState() as any;
+
+  logger.info("[skills-scanner] 🕐 检查定时任务...");
+
+  try {
+    // 尝试列出已有任务，JSON 格式
+    let existingId: string | undefined;
+    try {
+      const { stdout } = await execAsync("openclaw cron list --format json", { timeout: 8_000 });
+      const jobs: any[] = JSON.parse(stdout.trim());
+      const found = jobs.find((j: any) =>
+        j.name === CRON_JOB_NAME || j.jobName === CRON_JOB_NAME || j.id === state.cronJobId
+      );
+      if (found) {
+        existingId = found.id || found.jobId || state.cronJobId;
+        logger.info(`[skills-scanner] ✅ 定时任务已存在: ${existingId}`);
+        if (state.cronJobId !== existingId) {
+          saveState({ ...state, cronJobId: existingId });
+        }
+        return;
+      }
+    } catch {
+      // --format json 不支持时，降级文本检查
+      try {
+        const { stdout } = await execAsync("openclaw cron list", { timeout: 8_000 });
+        if (stdout.includes(CRON_JOB_NAME)) {
+          logger.info(`[skills-scanner] ✅ 定时任务已存在（文本检测）`);
+          if (!state.cronJobId) {
+            saveState({ ...state, cronJobId: "detected" });
+          }
+          return;
+        }
+      } catch {
+        /* 继续尝试创建 */
+      }
+    }
+
+    // 创建新任务
+    logger.info("[skills-scanner] 📝 创建定时任务...");
+    const addCmd = [
+      "openclaw cron add",
+      `--name "${CRON_JOB_NAME}"`,
+      `--cron "${CRON_SCHEDULE}"`,
+      `--tz "${CRON_TIMEZONE}"`,
+      "--session isolated",
+      '--message "请执行 /skills-scanner scan --report 并把结果发送到此渠道"',
+      "--announce",
+    ].join(" ");
+
+    const { stdout: addOut } = await execAsync(addCmd, { timeout: 15_000 });
+
+    const idMatch = addOut.match(/(?:Job ID|jobId|id)[:\s]+([a-zA-Z0-9_-]+)/i);
+    const cronJobId = idMatch ? idMatch[1] : "created";
+    saveState({ ...state, cronJobId });
+    logger.info(`[skills-scanner] ✅ 定时任务创建成功: ${cronJobId}`);
+
+  } catch (err: any) {
+    logger.warn("[skills-scanner] ⚠️  自动注册定时任务失败，请手动执行：");
+    logger.info(`[skills-scanner]   openclaw cron add --name "${CRON_JOB_NAME}" --cron "${CRON_SCHEDULE}" --tz "${CRON_TIMEZONE}" --session isolated --message "请执行 /skills-scanner scan --report 并把结果发送到此渠道" --announce`);
+    logger.debug(`[skills-scanner] 错误: ${err.message}`);
+  }
+}
+
+export async function removeCronJob(jobId: string): Promise<void> {
+  await execAsync(`openclaw cron remove ${jobId}`, { timeout: 8_000 });
+}

package/src/deps.ts

@@ -0,0 +1,71 @@
+/**
+ * Python 依赖管理模块
+ */
+
+import { exec } from "child_process";
+import { existsSync, rmSync } from "fs";
+import { join } from "path";
+import { promisify } from "util";
+import type { PluginLogger } from "openclaw/plugin-sdk";
+
+const execAsync = promisify(exec);
+
+export async function hasUv(): Promise<boolean> {
+  try {
+    await execAsync("uv --version");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isVenvReady(venvPython: string): Promise<boolean> {
+  if (!existsSync(venvPython)) return false;
+  
+  try {
+    await execAsync(`"${venvPython}" -c "import requests"`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isVenvReadySync(venvPython: string): boolean {
+  return existsSync(venvPython);
+}
+
+export async function ensureDeps(
+  skillDir: string,
+  venvPython: string,
+  logger: PluginLogger
+): Promise<boolean> {
+  if (await isVenvReady(venvPython)) {
+    logger.info("[skills-scanner] Python 依赖已就绪（requests 已安装）");
+    return true;
+  }
+
+  if (!(await hasUv())) {
+    logger.warn("[skills-scanner] uv 未安装：brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh");
+    return false;
+  }
+
+  logger.info("[skills-scanner] 正在安装 Python 依赖...");
+
+  try {
+    const venvDir = join(skillDir, ".venv");
+    if (existsSync(venvDir)) {
+      logger.info("[skills-scanner] 清理旧的虚拟环境...");
+      rmSync(venvDir, { recursive: true, force: true });
+    }
+
+    await execAsync(`uv venv "${venvDir}" --python 3.10`);
+    logger.info("[skills-scanner] 虚拟环境创建完成");
+
+    await execAsync(`uv pip install --python "${venvPython}" requests>=2.31.0`);
+    logger.info("[skills-scanner] ✅ 依赖安装完成");
+    return true;
+  } catch (err: any) {
+    logger.error(`[skills-scanner] ⚠️  依赖安装失败: ${err.message}`);
+    return false;
+  }
+}

package/src/report.ts

@@ -0,0 +1,113 @@
+/**
+ * 日报生成模块
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync } from "fs";
+import { join, basename } from "path";
+import type { PluginLogger } from "openclaw/plugin-sdk";
+import { runScan } from "./scanner.js";
+import { loadState, saveState, STATE_DIR, expandPath } from "./state.js";
+import type { ScanRecord } from "./types.js";
+
+export async function buildDailyReport(
+  dirs: string[],
+  behavioral: boolean,
+  apiUrl: string,
+  useLLM: boolean,
+  policy: string,
+  venvPython: string,
+  scanScript: string,
+  logger: PluginLogger
+): Promise<string> {
+  const now = new Date();
+  const dateStr = now.toLocaleDateString("zh-CN", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  });
+  const timeStr = now.toLocaleTimeString("zh-CN", {
+    hour: "2-digit",
+    minute: "2-digit"
+  });
+  const jsonOut = join(STATE_DIR, `report-${now.toISOString().slice(0, 10)}.json`);
+  mkdirSync(STATE_DIR, { recursive: true });
+
+  let total = 0;
+  let safe = 0;
+  let unsafe = 0;
+  let errors = 0;
+  const unsafeList: string[] = [];
+  const allResults: ScanRecord[] = [];
+
+  for (const dir of dirs) {
+    const expanded = expandPath(dir);
+    if (!existsSync(expanded)) continue;
+    
+    const tmpJson = join(STATE_DIR, `tmp-${Date.now()}.json`);
+    await runScan("batch", expanded, venvPython, scanScript, {
+      behavioral,
+      recursive: true,
+      jsonOut: tmpJson,
+      apiUrl,
+      useLLM,
+      policy
+    });
+    
+    try {
+      const rows: ScanRecord[] = JSON.parse(readFileSync(tmpJson, "utf-8"));
+      try {
+        rmSync(tmpJson);
+      } catch {}
+      
+      for (const r of rows) {
+        allResults.push(r);
+        total++;
+        if (r.error) {
+          errors++;
+        } else if (r.is_safe) {
+          safe++;
+        } else {
+          unsafe++;
+          unsafeList.push(r.name || basename(r.path ?? ""));
+        }
+      }
+    } catch {
+      logger.warn(`[skills-scanner] 无法解析 ${tmpJson}`);
+    }
+  }
+
+  writeFileSync(jsonOut, JSON.stringify(allResults, null, 2));
+  saveState({
+    ...loadState(),
+    lastScanAt: now.toISOString(),
+    lastUnsafeSkills: unsafeList
+  });
+
+  const lines = [
+    `🔍 *Skills 安全日报* — ${dateStr} ${timeStr}`,
+    "─".repeat(36),
+  ];
+  
+  if (total === 0) {
+    lines.push("📭 未找到任何 Skill，请检查扫描目录。");
+  } else {
+    lines.push(`📊 扫描总计：${total} 个 Skill`);
+    lines.push(`✅ 安全：${safe} 个`);
+    lines.push(`❌ 问题：${unsafe} 个`);
+    if (errors) lines.push(`⚠️  错误：${errors} 个`);
+    
+    if (unsafe > 0) {
+      lines.push("", "🚨 *需要关注的 Skills：*");
+      for (const name of unsafeList) {
+        const r = allResults.find(x => (x.name || basename(x.path ?? "")) === name);
+        lines.push(`  • ${name} [${r?.max_severity ?? "?"}] — ${r?.findings ?? "?"} 条发现`);
+      }
+      lines.push("", "💡 运行 `/skills-scanner scan <路径> --detailed` 查看详情");
+    } else {
+      lines.push("", "🎉 所有 Skills 安全，未发现威胁。");
+    }
+  }
+  
+  lines.push("", `📁 完整报告：${jsonOut}`);
+  return lines.join("\n");
+}

package/src/scanner.ts

@@ -0,0 +1,45 @@
+/**
+ * 扫描执行模块
+ */
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import type { ScanOptions, ScanResult } from "./types.js";
+
+const execAsync = promisify(exec);
+
+export async function runScan(
+  mode: "scan" | "batch",
+  target: string,
+  venvPython: string,
+  scanScript: string,
+  opts: ScanOptions = {}
+): Promise<ScanResult> {
+  const args = [mode, target];
+  
+  if (opts.detailed) args.push("--detailed");
+  if (opts.behavioral) args.push("--behavioral");
+  if (opts.recursive) args.push("--recursive");
+  if (opts.useLLM) args.push("--llm");
+  if (opts.policy) args.push("--policy", opts.policy);
+  if (opts.jsonOut) args.push("--json", opts.jsonOut);
+  if (opts.apiUrl) args.unshift("--api-url", opts.apiUrl);
+
+  const cmd = `"${venvPython}" "${scanScript}" ${args.map(a => `"${a}"`).join(" ")}`;
+
+  const env = { ...process.env };
+  // 清除代理，避免本地服务连接被代理拦截
+  for (const k of ["http_proxy", "https_proxy", "HTTP_PROXY", "HTTPS_PROXY", "all_proxy", "ALL_PROXY"]) {
+    delete env[k];
+  }
+
+  try {
+    const { stdout, stderr } = await execAsync(cmd, { timeout: 180_000, env });
+    return { exitCode: 0, output: (stdout + stderr).trim() };
+  } catch (err: any) {
+    return {
+      exitCode: err.code ?? 1,
+      output: ((err.stdout ?? "") + (err.stderr ?? "") || err.message).trim()
+    };
+  }
+}

package/src/state.ts

@@ -0,0 +1,66 @@
+/**
+ * 状态管理模块
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import type { ScanState, ScannerConfig } from "./types.js";
+
+export const STATE_DIR = join(homedir(), ".openclaw", "skills-scanner");
+export const STATE_FILE = join(STATE_DIR, "state.json");
+export const QUARANTINE_DIR = join(STATE_DIR, "quarantine");
+
+export function loadState(): ScanState {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveState(state: ScanState): void {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+export function isFirstRun(cfg: ScannerConfig): boolean {
+  const state = loadState() as any;
+  if (state.configReviewed) return false;
+  
+  return (
+    !cfg.apiUrl &&
+    (!cfg.scanDirs || cfg.scanDirs.length === 0) &&
+    cfg.behavioral !== true &&
+    cfg.useLLM !== true &&
+    cfg.policy !== "strict" &&
+    cfg.policy !== "permissive" &&
+    cfg.preInstallScan !== "off" &&
+    cfg.onUnsafe !== "delete" &&
+    cfg.onUnsafe !== "warn"
+  );
+}
+
+export function markConfigReviewed(): void {
+  const state = loadState();
+  saveState({ ...state, configReviewed: true });
+}
+
+export function expandPath(p: string): string {
+  return p.replace(/^~/, homedir());
+}
+
+export function defaultScanDirs(): string[] {
+  const dirs = [
+    join(homedir(), ".openclaw", "skills"),
+    join(homedir(), ".openclaw", "workspace", "skills"),
+  ];
+  
+  dirs.forEach(dir => {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  });
+  
+  return dirs;
+}

package/src/types.ts

@@ -0,0 +1,47 @@
+/**
+ * Skills Scanner 类型定义
+ */
+
+export interface ScannerConfig {
+  apiUrl?: string;
+  scanDirs?: string[];
+  behavioral?: boolean;
+  useLLM?: boolean;
+  policy?: "strict" | "balanced" | "permissive";
+  preInstallScan?: "on" | "off";
+  onUnsafe?: "quarantine" | "delete" | "warn";
+}
+
+export interface ScanState {
+  lastScanAt?: string;
+  lastUnsafeSkills?: string[];
+  configReviewed?: boolean;
+  cronJobId?: string;
+  pendingAlerts?: string[];
+}
+
+export interface ScanOptions {
+  detailed?: boolean;
+  behavioral?: boolean;
+  recursive?: boolean;
+  jsonOut?: string;
+  apiUrl?: string;
+  useLLM?: boolean;
+  policy?: string;
+}
+
+export interface ScanResult {
+  exitCode: number;
+  output: string;
+}
+
+export interface ScanRecord {
+  name?: string;
+  path?: string;
+  is_safe?: boolean;
+  error?: string;
+  max_severity?: string;
+  findings?: number;
+}
+
+export type OnUnsafeAction = "quarantine" | "delete" | "warn";