@pwddd/skills-scanner 1.0.0

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,143 @@
+/**
+ * Cron job management module
+ */
+
+import { execSync } from "node:child_process";
+import { loadState, saveState } from "./state.js";
+
+const CRON_JOB_NAME = "skills-daily-report";
+const CRON_SCHEDULE = "0 8 * * *";
+const CRON_TIMEZONE = "Asia/Shanghai";
+
+export async function ensureCronJob(logger: any): Promise<void> {
+  const state = loadState() as any;
+
+  logger.info("[skills-scanner] ─────────────────────────────────────");
+  logger.info("[skills-scanner] 🕐 Checking cron job...");
+
+  try {
+    let jobs: any[] = [];
+    try {
+      const listResult = execSync("openclaw cron list --format json", {
+        encoding: "utf-8",
+        timeout: 5000,
+      });
+      jobs = JSON.parse(listResult.trim());
+    } catch (listErr: any) {
+      logger.debug("[skills-scanner] JSON format not supported, trying text parsing");
+      try {
+        const listResult = execSync("openclaw cron list", {
+          encoding: "utf-8",
+          timeout: 5000,
+        });
+        if (listResult.includes(CRON_JOB_NAME)) {
+          logger.info(`[skills-scanner] ✅ Found existing job: ${CRON_JOB_NAME}`);
+          if (!state.cronJobId) {
+            saveState({ ...state, cronJobId: "manual-created" });
+          }
+          return;
+        }
+      } catch {
+        logger.debug("[skills-scanner] Cannot list cron jobs, may be permission issue");
+      }
+    }
+
+    const existingJob = jobs.find(
+      (j: any) =>
+        j.name === CRON_JOB_NAME ||
+        j.jobName === CRON_JOB_NAME ||
+        j.id === state.cronJobId
+    );
+
+    if (existingJob) {
+      const jobId = existingJob.id || existingJob.jobId || state.cronJobId;
+
+      const needsUpdate =
+        existingJob.schedule !== CRON_SCHEDULE ||
+        existingJob.timezone !== CRON_TIMEZONE;
+
+      if (needsUpdate) {
+        logger.info(`[skills-scanner] 🔄 Job config changed, updating...`);
+        try {
+          execSync(`openclaw cron remove ${jobId}`, {
+            encoding: "utf-8",
+            timeout: 5000,
+          });
+          logger.info(`[skills-scanner] ✅ Removed old job: ${jobId}`);
+        } catch (removeErr: any) {
+          logger.warn(`[skills-scanner] ⚠️  Failed to remove old job: ${removeErr.message}`);
+          if (state.cronJobId !== jobId) {
+            saveState({ ...state, cronJobId: jobId });
+          }
+          logger.info(`[skills-scanner] ✅ Keeping existing job: ${jobId}`);
+          return;
+        }
+      } else {
+        if (state.cronJobId !== jobId) {
+          saveState({ ...state, cronJobId: jobId });
+          logger.info(`[skills-scanner] ✅ Found existing job: ${jobId}`);
+        } else {
+          logger.info(`[skills-scanner] ✅ Job already exists: ${jobId}`);
+        }
+        return;
+      }
+    }
+
+    logger.info("[skills-scanner] 📝 Creating cron job...");
+
+    const cronCmd = [
+      "openclaw cron add",
+      `--name "${CRON_JOB_NAME}"`,
+      `--cron "${CRON_SCHEDULE}"`,
+      `--tz "${CRON_TIMEZONE}"`,
+      "--session isolated",
+      '--message "Please run /skills-scanner scan --report and send results to this channel"',
+      "--announce",
+    ].join(" ");
+
+    const result = execSync(cronCmd, { encoding: "utf-8", timeout: 10000 });
+
+    const jobIdMatch =
+      result.match(/Job ID[:\s]+([a-zA-Z0-9-]+)/i) ||
+      result.match(/jobId[:\s]+([a-zA-Z0-9-]+)/i) ||
+      result.match(/id[:\s]+([a-zA-Z0-9-]+)/i);
+
+    if (jobIdMatch) {
+      const cronJobId = jobIdMatch[1];
+      saveState({ ...state, cronJobId });
+      logger.info(`[skills-scanner] ✅ Job created successfully: ${cronJobId}`);
+      logger.info(
+        `[skills-scanner] 📅 Schedule: Daily at ${CRON_SCHEDULE.split(" ")[1]}:${CRON_SCHEDULE.split(" ")[0]} (${CRON_TIMEZONE})`
+      );
+    } else {
+      logger.info("[skills-scanner] ✅ Job creation command executed");
+      logger.debug(`[skills-scanner] Output: ${result.trim()}`);
+      saveState({ ...state, cronJobId: "created-unknown-id" });
+    }
+  } catch (err: any) {
+    logger.warn("[skills-scanner] ⚠️  Auto-registration failed");
+    logger.debug(`[skills-scanner] Error details: ${err.message}`);
+
+    if (err.message.includes("permission") || err.message.includes("EACCES")) {
+      logger.error("[skills-scanner] ❌ Permission denied, please run with admin privileges");
+    } else if (
+      err.message.includes("command not found") ||
+      err.message.includes("ENOENT")
+    ) {
+      logger.error("[skills-scanner] ❌ openclaw command not found, please check installation");
+    } else {
+      logger.info("[skills-scanner] 💡 Please manually register cron job:");
+      logger.info("[skills-scanner]");
+      logger.info("[skills-scanner]   openclaw cron add \\");
+      logger.info(`[skills-scanner]     --name "${CRON_JOB_NAME}" \\`);
+      logger.info(`[skills-scanner]     --cron "${CRON_SCHEDULE}" \\`);
+      logger.info(`[skills-scanner]     --tz "${CRON_TIMEZONE}" \\`);
+      logger.info("[skills-scanner]     --session isolated \\");
+      logger.info(
+        '[skills-scanner]     --message "Please run /skills-scanner scan --report and send results to this channel" \\'
+      );
+      logger.info("[skills-scanner]     --announce");
+      logger.info("[skills-scanner]");
+    }
+  }
+}

package/src/deps.ts

@@ -0,0 +1,73 @@
+/**
+ * Dependency management module
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, rmSync } from "node:fs";
+import { promisify } from "node:util";
+import { exec } from "node:child_process";
+import { join } from "node:path";
+
+const execAsync = promisify(exec);
+
+export function hasUv(): boolean {
+  try {
+    execSync("uv --version", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isVenvReady(venvPython: string): boolean {
+  if (!existsSync(venvPython)) return false;
+
+  try {
+    execSync(`"${venvPython}" -c "import requests"`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDeps(
+  skillDir: string,
+  venvPython: string,
+  logger: any
+): Promise<boolean> {
+  if (isVenvReady(venvPython)) {
+    logger.info("[skills-scanner] Python dependencies ready (requests installed)");
+    return true;
+  }
+
+  if (!hasUv()) {
+    logger.warn(
+      "[skills-scanner] uv not installed: brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh"
+    );
+    return false;
+  }
+
+  logger.info("[skills-scanner] Installing Python dependencies...");
+
+  try {
+    const venvDir = join(skillDir, ".venv");
+
+    if (existsSync(venvDir)) {
+      logger.info("[skills-scanner] Cleaning old virtual environment...");
+      rmSync(venvDir, { recursive: true, force: true });
+    }
+
+    await execAsync(`uv venv "${venvDir}" --python 3.10`);
+    logger.info("[skills-scanner] Virtual environment created");
+
+    logger.info("[skills-scanner] Installing requests...");
+    await execAsync(`uv pip install --python "${venvPython}" requests>=2.31.0`);
+
+    execSync(`"${venvPython}" -c "import requests"`, { stdio: "ignore" });
+    logger.info("[skills-scanner] ✅ Dependencies installed successfully");
+    return true;
+  } catch (err: any) {
+    logger.error(`[skills-scanner] ⚠️  Dependency installation failed: ${err.message}`);
+    return false;
+  }
+}

package/src/prompt-guidance.ts

@@ -0,0 +1,25 @@
+/**
+ * System prompt guidance for Skills security scanning
+ */
+
+export const SKILLS_SECURITY_GUIDANCE = [
+  "## Skills 安全规则",
+  "",
+  "当用户请求安装、下载或使用新的 Skill 时，必须先运行安全扫描：",
+  "",
+  "1. 使用 `/skills-scanner scan <skill路径>` 进行扫描",
+  "2. 等待扫描结果",
+  "3. 根据结果决定：",
+  "   - ✅ 安全（is_safe=true）：可以继续安装，告知用户扫描通过",
+  "   - ❌ 不安全（is_safe=false）：",
+  "     * 立即告知用户发现的安全问题",
+  "     * 显示威胁详情（严重级别、发现数量）",
+  "     * 不得继续安装，除非用户明确要求忽略风险",
+  "",
+  "对于来自不可信来源的 Skill，使用 `--detailed --behavioral` 进行深度扫描。",
+  "",
+  "用户明确绕过风险时，必须：",
+  "1. 再次明确告知风险",
+  "2. 要求用户确认（\"我了解风险并仍要继续\"）",
+  "3. 建议用户监控该 Skill 的行为",
+].join("\n");

package/src/report.ts

@@ -0,0 +1,100 @@
+/**
+ * Report generation module
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join, basename } from "node:path";
+import { runScan } from "./scanner.js";
+import { loadState, saveState, STATE_DIR } from "./state.js";
+import type { ScanRecord } from "./types.js";
+
+export async function buildDailyReport(
+  dirs: string[],
+  behavioral: boolean,
+  apiUrl: string,
+  useLLM: boolean,
+  policy: string,
+  logger: any,
+  venvPython: string,
+  scanScript: string
+): Promise<string> {
+  const now = new Date();
+  const dateStr = now.toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  });
+  const timeStr = now.toLocaleTimeString("en-US", {
+    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) {
+    if (!existsSync(dir)) continue;
+    const tmpJson = join(STATE_DIR, `tmp-${Date.now()}.json`);
+    await runScan(venvPython, scanScript, "batch", dir, {
+      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] Cannot parse ${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,50 @@
+/**
+ * Scanner module - handles Python script execution
+ */
+
+import { promisify } from "node:util";
+import { exec } from "node:child_process";
+import type { ScanOptions, ScanResult } from "./types.js";
+
+const execAsync = promisify(exec);
+
+export async function runScan(
+  venvPython: string,
+  scanScript: string,
+  mode: "scan" | "batch",
+  target: 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(" ")}`;
+
+  try {
+    const env = { ...process.env };
+    // Remove proxy env vars to avoid connection issues
+    delete env.http_proxy;
+    delete env.https_proxy;
+    delete env.HTTP_PROXY;
+    delete env.HTTPS_PROXY;
+    delete env.all_proxy;
+    delete env.ALL_PROXY;
+
+    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 || "").trim() || err.message,
+    };
+  }
+}

package/src/state.ts

@@ -0,0 +1,70 @@
+/**
+ * State management module
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, homedir } from "node:path";
+import type { ScanState, ScannerConfig } from "./types.js";
+
+const STATE_DIR = join(homedir(), ".openclaw", "skills-scanner");
+const STATE_FILE = join(STATE_DIR, "state.json");
+
+export function loadState(): ScanState {
+  try {
+    return JSON.parse(readFileSync(STATE_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+
+export function saveState(s: ScanState): void {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(STATE_FILE, JSON.stringify(s, null, 2));
+}
+
+export function isFirstRun(cfg: ScannerConfig): boolean {
+  const state = loadState() as any;
+
+  if (state.configReviewed) {
+    return false;
+  }
+
+  const isDefaultConfig =
+    !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";
+
+  return isDefaultConfig;
+}
+
+export function markConfigReviewed(): void {
+  const state = loadState() as any;
+  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"),
+  ];
+
+  for (const dir of dirs) {
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  return dirs;
+}
+
+export { STATE_DIR, STATE_FILE };

package/src/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Skills Scanner 类型定义
+ */
+
+export interface ScannerConfig {
+  apiUrl?: string;
+  scanDirs?: string[];
+  behavioral?: boolean;
+  useLLM?: boolean;
+  policy?: "strict" | "balanced" | "permissive";
+  preInstallScan?: "on" | "off";
+  onUnsafe?: "quarantine" | "delete" | "warn";
+  injectSecurityGuidance?: boolean;
+}
+
+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";