@pwddd/skills-scanner 1.0.0-beta.1

package/index.ts

@@ -0,0 +1,647 @@
+/**
+ * OpenClaw Plugin: skills-scanner
+ *
+ * Security scanner for OpenClaw Skills to detect potential threats.
+ */
+
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { join } from "node:path";
+import os from "node:os";
+import { existsSync } from "node:fs";
+import type { ScannerConfig } from "./src/types.js";
+import { skillsScannerConfigSchema, generateConfigGuide } from "./src/config.js";
+import {
+  loadState,
+  saveState,
+  expandPath,
+  defaultScanDirs,
+  isFirstRun,
+  markConfigReviewed,
+  getStateDir,
+} from "./src/state.js";
+import { runScan } from "./src/scanner.js";
+import { buildDailyReport } from "./src/report.js";
+import { ensureCronJobViaGateway, checkCronJobStatus } from "./src/cron-manager.js";
+import { startWatcher } from "./src/watcher.js";
+import { createCommandHandlers } from "./src/commands.js";
+import { SKILLS_SECURITY_GUIDANCE } from "./src/prompt-guidance.js";
+import { PROMPT_INJECTION_GUARD } from "./src/prompt-injection-guard.js";
+import { HIGH_RISK_OPERATION_GUARD } from "./src/high-risk-operation-guard.js";
+import { handleBeforeInstall } from "./src/before-install-hook.js";
+import type { BeforeInstallEvent } from "./src/before-install-hook.js";
+import { validateConfig } from "./src/config-validator.js";
+import { getMetricsSummary } from "./src/metrics.js";
+import { debugLog, isDebugMode } from "./src/debug.js";
+
+// Constants
+const PLUGIN_ROOT = process.env.OPENCLAW_PLUGIN_ROOT || __dirname;
+
+export default definePluginEntry({
+  id: "skills-scanner",
+  name: "Skills Scanner",
+  description: "Security scanner for OpenClaw Skills to detect potential threats",
+  configSchema: skillsScannerConfigSchema,
+  register(api) {
+  // Get state directory using official API
+  const STATE_DIR = getStateDir(api.runtime);
+  const QUARANTINE_DIR = join(STATE_DIR, "quarantine");
+
+  const cfg: ScannerConfig =
+    api.config?.plugins?.entries?.["skills-scanner"]?.config ?? {};
+
+  // Validate configuration
+  const validation = validateConfig(cfg, api.logger);
+  if (!validation.valid) {
+    api.logger.error("[skills-scanner] ❌ Invalid configuration, plugin may not work correctly");
+    // Continue loading but with warnings
+  }
+
+  const apiUrl = cfg.apiUrl ?? "https://110.vemic.com/skills-scanner";
+  const scanDirs =
+    (cfg.scanDirs?.map(expandPath) ?? []).filter(existsSync).length > 0
+      ? cfg.scanDirs!.map(expandPath)
+      : defaultScanDirs();
+  const behavioral = cfg.behavioral ?? false;
+  const useLLM = cfg.useLLM ?? false;
+  const policy = cfg.policy ?? "balanced";
+  const preInstallScan = cfg.preInstallScan ?? "on";
+  const onUnsafe = cfg.onUnsafe ?? "warn";
+  const injectSecurityGuidance = cfg.injectSecurityGuidance ?? true;
+  const enablePromptInjectionGuard = cfg.enablePromptInjectionGuard ?? false;
+  const enableHighRiskOperationGuard = cfg.enableHighRiskOperationGuard ?? false;
+  const enableBeforeInstallHook = cfg.enableBeforeInstallHook ?? true;
+
+  api.logger.info("[skills-scanner] ═══════════════════════════════════════");
+  api.logger.info("[skills-scanner] Plugin loading...");
+  api.logger.info(`[skills-scanner] API URL: ${apiUrl}`);
+  api.logger.info(`[skills-scanner] Scan directories: ${scanDirs.join(", ")}`);
+  api.logger.info(`[skills-scanner] Before-install hook: ${enableBeforeInstallHook ? "✅ ENABLED" : "❌ DISABLED"}`);
+
+  if (isDebugMode()) {
+    api.logger.info("[skills-scanner] 🐛 DEBUG MODE ENABLED");
+    debugLog(api.logger, "Full configuration", cfg);
+  }
+
+  // Inject system prompt guidance (can be disabled via config)
+  if (injectSecurityGuidance) {
+    // Build combined guidance
+    const guidanceParts = [SKILLS_SECURITY_GUIDANCE];
+
+    if (enablePromptInjectionGuard) {
+      guidanceParts.push(PROMPT_INJECTION_GUARD);
+    }
+
+    if (enableHighRiskOperationGuard) {
+      guidanceParts.push(HIGH_RISK_OPERATION_GUARD);
+    }
+
+    const combinedGuidance = guidanceParts.join("\n\n");
+
+    api.on("before_prompt_build", async () => ({
+      prependSystemContext: combinedGuidance,
+    }));
+
+    api.logger.info("[skills-scanner] ✅ Security guidance injected into system prompt");
+    if (enablePromptInjectionGuard) {
+      api.logger.info("[skills-scanner]    - Prompt injection guard enabled");
+    }
+    if (enableHighRiskOperationGuard) {
+      api.logger.info("[skills-scanner]    - High-risk operation guard enabled");
+    }
+  } else {
+    api.logger.info("[skills-scanner] ⏭️  Security guidance injection disabled");
+  }
+
+  // Register before_install hook (CRITICAL SECURITY GATE)
+  if (enableBeforeInstallHook) {
+    api.on("before_install", async (event: BeforeInstallEvent) => {
+      try {
+        return await handleBeforeInstall(event, {
+          apiUrl,
+          behavioral,
+          useLLM,
+          policy,
+          logger: api.logger,
+          enabled: enableBeforeInstallHook,
+          timeoutMs: cfg.scanTimeoutMs || 30000, // Use configured timeout or 30s default
+        });
+      } catch (err: any) {
+        api.logger.error("[skills-scanner] ❌ before_install hook error", {
+          error: err.message,
+          stack: err.stack,
+          skillPath: event.skillPath,
+        });
+        // Return safe default on error - allow installation but log the failure
+        return { block: false };
+      }
+    });
+
+    api.logger.info("[skills-scanner] 🛡️  before_install hook registered (installation interception active)");
+  } else {
+    api.logger.warn("[skills-scanner] ⚠️  before_install hook DISABLED - installations will NOT be intercepted!");
+  }
+
+  // Register gateway_start hook for automatic cron job registration
+  api.on("gateway_start", async () => {
+    try {
+      api.logger.info("[skills-scanner] 🚀 Gateway started, checking cron job...");
+      await ensureCronJobViaGateway({
+        logger: api.logger,
+        callGateway: async (method: string, params: any) => {
+          return await api.callGateway(method, params);
+        },
+      });
+      api.logger.info("[skills-scanner] ✅ Cron job check completed");
+    } catch (err: any) {
+      api.logger.error("[skills-scanner] ❌ Cron job registration failed", {
+        error: err.message,
+        stack: err.stack,
+      });
+      // Don't throw - avoid blocking gateway startup
+    }
+  });
+
+  // Register plugin_uninstall hook for cleanup
+  api.on("plugin_uninstall", async () => {
+    api.logger.info("[skills-scanner] 🗑️  Plugin uninstalling, cleaning up...");
+
+    try {
+      // 1. Stop file watcher
+      if (stopWatcher) {
+        api.logger.debug("[skills-scanner] Stopping file watcher...");
+        stopWatcher();
+        stopWatcher = null;
+        api.logger.debug("[skills-scanner] ✅ File watcher stopped");
+      }
+
+      // 2. Remove cron jobs
+      try {
+        const listResult = await api.callGateway("cron.list", {});
+        const jobs = listResult?.jobs || [];
+        const ourJobs = jobs.filter((j: any) => j.name === "skills-weekly-report");
+
+        for (const job of ourJobs) {
+          const jobId = job.jobId || job.id;
+          await api.callGateway("cron.remove", { jobId });
+          api.logger.info("[skills-scanner] Removed cron job", { jobId });
+        }
+
+        if (ourJobs.length > 0) {
+          api.logger.info(`[skills-scanner] ✅ Removed ${ourJobs.length} cron job(s)`);
+        }
+      } catch (err: any) {
+        api.logger.warn("[skills-scanner] Failed to remove cron jobs", {
+          error: err.message,
+        });
+      }
+
+      // 3. Save final state
+      try {
+        const finalState = loadState(api.runtime);
+        finalState.lastUninstallAt = new Date().toISOString();
+        saveState(finalState, api.runtime);
+        api.logger.debug("[skills-scanner] ✅ Final state saved");
+      } catch (err: any) {
+        api.logger.warn("[skills-scanner] Failed to save final state", {
+          error: err.message,
+        });
+      }
+
+      api.logger.info("[skills-scanner] ✅ Cleanup completed successfully");
+    } catch (err: any) {
+      api.logger.error("[skills-scanner] ❌ Cleanup failed", {
+        error: err.message,
+        stack: err.stack,
+      });
+    }
+  });
+
+  // Register config_changed hook for hot reload
+  api.on("config_changed", async (newConfig: any) => {
+    api.logger.info("[skills-scanner] 🔄 Configuration changed, reloading...");
+
+    try {
+      const newCfg: ScannerConfig =
+        newConfig?.plugins?.entries?.["skills-scanner"]?.config ?? {};
+
+      // Validate new configuration
+      const validation = validateConfig(newCfg, api.logger);
+      if (!validation.valid) {
+        api.logger.error("[skills-scanner] ❌ Invalid new configuration, keeping old config");
+        return;
+      }
+
+      // Check what changed
+      const apiUrlChanged = newCfg.apiUrl !== cfg.apiUrl;
+      const scanDirsChanged = JSON.stringify(newCfg.scanDirs) !== JSON.stringify(cfg.scanDirs);
+      const preInstallScanChanged = newCfg.preInstallScan !== cfg.preInstallScan;
+
+      if (apiUrlChanged) {
+        api.logger.info("[skills-scanner] API URL updated", {
+          old: cfg.apiUrl,
+          new: newCfg.apiUrl,
+        });
+        // Update global apiUrl variable
+        Object.assign(cfg, { apiUrl: newCfg.apiUrl });
+      }
+
+      if (scanDirsChanged || preInstallScanChanged) {
+        api.logger.info("[skills-scanner] Scan configuration updated, restarting watcher...");
+
+        // Stop old watcher
+        if (stopWatcher) {
+          stopWatcher();
+          stopWatcher = null;
+        }
+
+        // Start new watcher with updated config
+        const newScanDirs =
+          (newCfg.scanDirs?.map(expandPath) ?? []).filter(existsSync).length > 0
+            ? newCfg.scanDirs!.map(expandPath)
+            : defaultScanDirs();
+
+        if (newCfg.preInstallScan === "on" && newScanDirs.length > 0) {
+          stopWatcher = startWatcher(
+            newScanDirs,
+            newCfg.onUnsafe ?? "warn",
+            newCfg.behavioral ?? false,
+            newCfg.apiUrl ?? apiUrl,
+            newCfg.useLLM ?? false,
+            newCfg.policy ?? "balanced",
+            persistWatcherAlert,
+            api.logger,
+            QUARANTINE_DIR
+          );
+          api.logger.info("[skills-scanner] ✅ Watcher restarted with new configuration");
+        } else {
+          api.logger.info("[skills-scanner] ⏭️  Watcher disabled by new configuration");
+        }
+
+        // Update global config
+        Object.assign(cfg, newCfg);
+      }
+
+      api.logger.info("[skills-scanner] ✅ Configuration reload completed");
+    } catch (err: any) {
+      api.logger.error("[skills-scanner] ❌ Configuration reload failed", {
+        error: err.message,
+        stack: err.stack,
+      });
+    }
+  });
+
+  // Check if first run
+  const firstRun = isFirstRun(cfg, api.runtime);
+  if (firstRun) {
+    api.logger.info("[skills-scanner] 🎉 First run detected");
+    const configGuide = generateConfigGuide(
+      cfg,
+      apiUrl,
+      scanDirs,
+      behavioral,
+      useLLM,
+      policy,
+      preInstallScan,
+      onUnsafe
+    );
+    console.log(configGuide);
+    markConfigReviewed(api.runtime);
+  }
+
+  // Helper for watcher alerts
+  function persistWatcherAlert(msg: string): void {
+    const state = loadState(api.runtime);
+    const alerts: string[] = (state as any).pendingAlerts ?? [];
+    alerts.push(`[${new Date().toLocaleString("en-US")}] ${msg}`);
+    saveState({ ...state, pendingAlerts: alerts } as any, api.runtime);
+    api.logger.warn(`[skills-scanner] ${msg}`);
+  }
+
+  // Service: start watcher
+  let stopWatcher: (() => void) | null = null;
+
+  api.registerService({
+    id: "skills-scanner-setup",
+    start: async () => {
+      api.logger.info("[skills-scanner] 🚀 Service starting...");
+
+      if (preInstallScan === "on" && scanDirs.length > 0) {
+        api.logger.info(`[skills-scanner] 📁 Starting file monitoring: ${scanDirs.length} directories`);
+        stopWatcher = startWatcher(
+          scanDirs,
+          onUnsafe,
+          behavioral,
+          apiUrl,
+          useLLM,
+          policy,
+          persistWatcherAlert,
+          api.logger,
+          QUARANTINE_DIR
+        );
+        api.logger.info("[skills-scanner] ✅ File monitoring started");
+      } else {
+        api.logger.info("[skills-scanner] ⏭️  Pre-install scan disabled");
+      }
+    },
+    stop: async () => {
+      api.logger.info("[skills-scanner] 🛑 Service stopping...");
+
+      try {
+        // 1. Stop file watcher
+        if (stopWatcher) {
+          api.logger.debug("[skills-scanner] Stopping file watcher...");
+          stopWatcher();
+          stopWatcher = null;
+          api.logger.debug("[skills-scanner] ✅ File watcher stopped");
+        }
+
+        // 2. Save final state
+        try {
+          const finalState = loadState(api.runtime);
+          finalState.lastShutdownAt = new Date().toISOString();
+          saveState(finalState, api.runtime);
+          api.logger.debug("[skills-scanner] ✅ Final state saved");
+        } catch (err: any) {
+          api.logger.warn("[skills-scanner] Failed to save final state", {
+            error: err.message,
+          });
+        }
+
+        // 3. Clear pending alerts (optional - keep for next run)
+        // This is intentionally commented out to preserve alerts
+        // const state = loadState(api.runtime);
+        // if ((state as any).pendingAlerts?.length > 0) {
+        //   saveState({ ...state, pendingAlerts: [] } as any, api.runtime);
+        // }
+
+        api.logger.info("[skills-scanner] ✅ Service stopped cleanly");
+      } catch (err: any) {
+        api.logger.error("[skills-scanner] ❌ Error during shutdown", {
+          error: err.message,
+          stack: err.stack,
+        });
+      }
+    },
+  });
+
+  // Health check endpoint
+  api.registerHttpRoute({
+    method: "GET",
+    path: "/health/skills-scanner",
+    handler: async (req, res) => {
+      try {
+        const state = loadState(api.runtime);
+
+        // Check API availability
+        let apiStatus = "unknown";
+        try {
+          const response = await fetch(`${apiUrl}/health`, {
+            signal: AbortSignal.timeout(3000),
+          });
+          apiStatus = response.ok ? "available" : "unavailable";
+        } catch {
+          apiStatus = "unavailable";
+        }
+
+        // Get performance metrics
+        const metrics = getMetricsSummary(STATE_DIR);
+
+        const health = {
+          status: "healthy",
+          plugin: {
+            version: api.version || "1.0.0",
+            id: api.id,
+            name: api.name,
+          },
+          api: {
+            url: apiUrl,
+            status: apiStatus,
+          },
+          watcher: {
+            enabled: preInstallScan === "on",
+            running: stopWatcher !== null,
+            directories: scanDirs.length,
+          },
+          state: {
+            lastScanAt: state.lastScanAt || null,
+            lastShutdownAt: state.lastShutdownAt || null,
+            pendingAlerts: (state as any).pendingAlerts?.length || 0,
+          },
+          metrics: {
+            totalScans: metrics.totalScans,
+            successRate: metrics.successRate.toFixed(2) + "%",
+            averageDurationMs: metrics.averageDurationMs,
+            lastScanAt: metrics.lastScanAt || null,
+          },
+          config: {
+            policy,
+            behavioral,
+            useLLM,
+            beforeInstallHook: enableBeforeInstallHook,
+          },
+          timestamp: new Date().toISOString(),
+        };
+
+        res.status(200).json(health);
+      } catch (err: any) {
+        api.logger.error("[skills-scanner] Health check failed", {
+          error: err.message,
+        });
+
+        res.status(503).json({
+          status: "unhealthy",
+          error: err.message,
+          timestamp: new Date().toISOString(),
+        });
+      }
+    },
+  });
+
+  // Command handlers
+  const handlers = createCommandHandlers(
+    cfg,
+    apiUrl,
+    scanDirs,
+    behavioral,
+    useLLM,
+    policy,
+    preInstallScan,
+    onUnsafe,
+    api.logger,
+    async (method: string, params: any) => {
+      return await api.callGateway(method, params);
+    }
+  );
+
+  // Chat command: /skills-scanner
+  api.registerCommand({
+    name: "skills-scanner",
+    description: "Skills 安全扫描工具。用法：/skills-scanner <子命令> [参数]",
+    acceptsArgs: true,
+    requireAuth: true,
+    handler: async (ctx: any) => {
+      const args = (ctx.args ?? "").trim();
+
+      if (!args) {
+        return {
+          text: [
+            "🔍 *Skills Scanner - 安全扫描工具*",
+            "",
+            "可用命令:",
+            "• `/skills-scanner scan <路径> [选项]` - 扫描 Skill",
+            "• `/skills-scanner scan clawhub <URL> [选项]` - 扫描 ClawHub Skill",
+            "• `/skills-scanner health` - 健康检查",
+            "• `/skills-scanner config [操作]` - 配置管理",
+            "• `/skills-scanner cron [操作]` - 定时任务管理",
+            "",
+            "扫描选项:",
+            "• `--detailed` - 显示详细发现",
+            "• `--behavioral` - 启用行为分析",
+            "• `--recursive` - 递归扫描子目录",
+            "• `--report` - 生成日报格式",
+            "",
+            "示例:",
+            "```",
+            "/skills-scanner scan ~/my-skill",
+            "/skills-scanner scan ~/skills --recursive",
+            "/skills-scanner scan clawhub https://clawhub.ai/username/project",
+            "/skills-scanner health",
+            "```",
+            "",
+            "💡 使用 `/skills-scanner help` 查看详细帮助",
+          ].join("\n"),
+        };
+      }
+
+      const parts = args.split(/\s+/);
+      const subCommand = parts[0].toLowerCase();
+      const subArgs = parts.slice(1).join(" ");
+
+      if (subCommand === "scan") {
+        return await handlers.handleScanCommand(subArgs);
+      } else if (subCommand === "health") {
+        return await handlers.handleHealthCommand();
+      } else if (subCommand === "config") {
+        return await handlers.handleConfigCommand(subArgs);
+      } else if (subCommand === "cron") {
+        return await handlers.handleCronCommand(subArgs);
+      } else if (subCommand === "help" || subCommand === "--help" || subCommand === "-h") {
+        return { text: handlers.getHelpText() };
+      } else {
+        return {
+          text: `❌ 未知子命令：${subCommand}\n\n使用 \`/skills-scanner help\` 查看帮助`,
+        };
+      }
+    },
+  });
+
+  // Gateway RPC methods
+  api.registerGatewayMethod("skillsScanner.scan", async ({ respond, params }: any) => {
+    const { path: p, mode = "scan", recursive = false, detailed = false } = params ?? {};
+    if (!p) return respond(false, { error: "Missing path parameter" });
+
+    try {
+      const res = await runScan(mode === "batch" ? "batch" : "scan", expandPath(p), {
+        recursive,
+        detailed,
+        behavioral,
+        apiUrl,
+        useLLM,
+        policy,
+      });
+      respond(res.exitCode === 0, {
+        output: res.output,
+        exitCode: res.exitCode,
+        is_safe: res.exitCode === 0,
+        data: res.data,
+      });
+    } catch (err: any) {
+      respond(false, { error: err.message });
+    }
+  });
+
+  api.registerGatewayMethod("skillsScanner.report", async ({ respond }: any) => {
+    if (scanDirs.length === 0) return respond(false, { error: "No scan directories found" });
+    try {
+      const report = await buildDailyReport(
+        scanDirs,
+        behavioral,
+        apiUrl,
+        useLLM,
+        policy,
+        api.logger
+      );
+      respond(true, { report, state: loadState() });
+    } catch (err: any) {
+      respond(false, { error: err.message });
+    }
+  });
+
+  // CLI commands
+  api.registerCli(
+    ({ program }: any) => {
+      const cmd = program.command("skills-scanner").description("OpenClaw Skills 安全扫描工具");
+
+      cmd
+        .command("scan <path>")
+        .description("扫描单个 Skill")
+        .option("--detailed", "显示所有发现")
+        .option("--behavioral", "启用行为分析")
+        .action(async (p: string, opts: any) => {
+          const res = await runScan("scan", expandPath(p), {
+            ...opts,
+            apiUrl,
+            useLLM,
+            policy,
+          });
+          console.log(res.output);
+          process.exit(res.exitCode);
+        });
+
+      cmd
+        .command("batch <directory>")
+        .description("批量扫描目录")
+        .option("--recursive", "递归扫描子目录")
+        .option("--detailed", "显示所有发现")
+        .option("--behavioral", "启用行为分析")
+        .action(async (d: string, opts: any) => {
+          const res = await runScan("batch", expandPath(d), {
+            ...opts,
+            apiUrl,
+            useLLM,
+            policy,
+          });
+          console.log(res.output);
+          process.exit(res.exitCode);
+        });
+
+      cmd
+        .command("report")
+        .description("生成日报")
+        .action(async () => {
+          const report = await buildDailyReport(
+            scanDirs,
+            behavioral,
+            apiUrl,
+            useLLM,
+            policy,
+            console
+          );
+          console.log(report);
+        });
+
+      cmd
+        .command("health")
+        .description("检查 API 服务健康状态")
+        .action(async () => {
+          const res = await runScan("health", "", { apiUrl });
+          console.log(res.output);
+          process.exit(res.exitCode);
+        });
+    },
+    { commands: ["skills-scanner"] }
+  );
+
+  api.logger.info("[skills-scanner] ✅ Plugin registered");
+  },
+});