@pwddd/skills-scanner 1.0.0

package/index.ts

@@ -0,0 +1,373 @@
+/**
+ * OpenClaw Plugin: skills-scanner
+ *
+ * Security scanner for OpenClaw Skills to detect potential threats.
+ */
+
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { join } from "node:path";
+import { homedir } 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,
+} from "./src/state.js";
+import { ensureDeps, isVenvReady } from "./src/deps.js";
+import { runScan } from "./src/scanner.js";
+import { buildDailyReport } from "./src/report.js";
+import { ensureCronJob } from "./src/cron.js";
+import { startWatcher } from "./src/watcher.js";
+import { createCommandHandlers } from "./src/commands.js";
+import { SKILLS_SECURITY_GUIDANCE } from "./src/prompt-guidance.js";
+
+// Constants
+const PLUGIN_ROOT = process.env.OPENCLAW_PLUGIN_ROOT || __dirname;
+const SKILL_DIR = join(PLUGIN_ROOT, "skills", "skills-scanner");
+const VENV_PYTHON = join(SKILL_DIR, ".venv", "bin", "python");
+const SCAN_SCRIPT = join(SKILL_DIR, "scan.py");
+const STATE_DIR = join(homedir(), ".openclaw", "skills-scanner");
+const QUARANTINE_DIR = join(STATE_DIR, "quarantine");
+
+export default function register(api: OpenClawPluginApi) {
+  const cfg: ScannerConfig =
+    api.config?.plugins?.entries?.["skills-scanner"]?.config ?? {};
+  const apiUrl = cfg.apiUrl ?? "http://localhost:8000";
+  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 ?? "quarantine";
+  const injectSecurityGuidance = cfg.injectSecurityGuidance ?? 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] Python dependencies: ${isVenvReady(VENV_PYTHON) ? "✅ Ready" : "❌ Not installed"}`
+  );
+
+  // Inject system prompt guidance (can be disabled via config)
+  if (injectSecurityGuidance) {
+    api.on("before_prompt_build", async () => ({
+      prependSystemContext: SKILLS_SECURITY_GUIDANCE,
+    }));
+    api.logger.info("[skills-scanner] ✅ Security guidance injected into system prompt");
+  } else {
+    api.logger.info("[skills-scanner] ⏭️  Security guidance injection disabled");
+  }
+
+  // Check if first run
+  const firstRun = isFirstRun(cfg);
+  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();
+  }
+
+  // Install dependencies immediately
+  if (!isVenvReady(VENV_PYTHON)) {
+    api.logger.info("[skills-scanner] Installing Python dependencies...");
+    ensureDeps(SKILL_DIR, VENV_PYTHON, api.logger)
+      .then((success) => {
+        if (success) {
+          api.logger.info("[skills-scanner] ✅ Dependencies installed");
+        }
+      })
+      .catch((err) => {
+        api.logger.error(`[skills-scanner] Dependency installation failed: ${err.message}`);
+      });
+  }
+
+  // Helper for watcher alerts
+  function persistWatcherAlert(msg: string): void {
+    const state = loadState();
+    const alerts: string[] = (state as any).pendingAlerts ?? [];
+    alerts.push(`[${new Date().toLocaleString("en-US")}] ${msg}`);
+    saveState({ ...state, pendingAlerts: alerts } as any);
+    api.logger.warn(`[skills-scanner] ${msg}`);
+  }
+
+  // Service: Install deps + start watcher
+  let stopWatcher: (() => void) | null = null;
+
+  api.registerService({
+    id: "skills-scanner-setup",
+    start: async () => {
+      api.logger.info("[skills-scanner] 🚀 Service starting...");
+
+      const depsReady = await ensureDeps(SKILL_DIR, VENV_PYTHON, api.logger);
+
+      if (!depsReady) {
+        api.logger.error("[skills-scanner] ❌ Dependencies installation failed");
+        return;
+      }
+
+      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,
+          VENV_PYTHON,
+          SCAN_SCRIPT,
+          QUARANTINE_DIR
+        );
+        api.logger.info("[skills-scanner] ✅ File monitoring started");
+      } else {
+        api.logger.info("[skills-scanner] ⏭️  Pre-install scan disabled");
+      }
+
+      // Register cron job (only in Gateway mode)
+      const isGatewayMode = !!(api as any).runtime;
+      if (isGatewayMode) {
+        await ensureCronJob(api.logger);
+      }
+
+      api.logger.info("[skills-scanner] ─────────────────────────────────────");
+    },
+    stop: () => {
+      api.logger.info("[skills-scanner] 🛑 Service stopping...");
+      stopWatcher?.();
+      stopWatcher = null;
+    },
+  });
+
+  // Command handlers
+  const handlers = createCommandHandlers(
+    cfg,
+    apiUrl,
+    scanDirs,
+    behavioral,
+    useLLM,
+    policy,
+    preInstallScan,
+    onUnsafe,
+    VENV_PYTHON,
+    SCAN_SCRIPT,
+    api.logger
+  );
+
+  // 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 status` - 查看状态",
+            "• `/skills-scanner config [操作]` - 配置管理",
+            "• `/skills-scanner cron [操作]` - 定时任务管理",
+            "",
+            "扫描选项:",
+            "• `--detailed` - 显示详细发现",
+            "• `--behavioral` - 启用行为分析",
+            "• `--recursive` - 递归扫描子目录",
+            "• `--report` - 生成日报格式",
+            "",
+            "示例:",
+            "```",
+            "/skills-scanner scan ~/my-skill",
+            "/skills-scanner scan ~/skills --recursive",
+            "/skills-scanner status",
+            "```",
+            "",
+            "💡 使用 `/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 === "status") {
+        return await handlers.handleStatusCommand();
+      } 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" });
+    if (!isVenvReady(VENV_PYTHON))
+      return respond(false, { error: "Python dependencies not ready" });
+    const res = await runScan(VENV_PYTHON, SCAN_SCRIPT, 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,
+    });
+  });
+
+  api.registerGatewayMethod("skillsScanner.report", async ({ respond }: any) => {
+    if (!isVenvReady(VENV_PYTHON))
+      return respond(false, { error: "Python dependencies not ready" });
+    if (scanDirs.length === 0) return respond(false, { error: "No scan directories found" });
+    const report = await buildDailyReport(
+      scanDirs,
+      behavioral,
+      apiUrl,
+      useLLM,
+      policy,
+      api.logger,
+      VENV_PYTHON,
+      SCAN_SCRIPT
+    );
+    respond(true, { report, state: loadState() });
+  });
+
+  // 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(VENV_PYTHON, SCAN_SCRIPT, "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(VENV_PYTHON, SCAN_SCRIPT, "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,
+            VENV_PYTHON,
+            SCAN_SCRIPT
+          );
+          console.log(report);
+        });
+
+      cmd
+        .command("health")
+        .description("检查 API 服务健康状态")
+        .action(async () => {
+          if (!isVenvReady(VENV_PYTHON)) {
+            console.error("❌ Python 依赖未就绪");
+            process.exit(1);
+          }
+
+          try {
+            const { exec } = await import("node:child_process");
+            const { promisify } = await import("node:util");
+            const execAsync = promisify(exec);
+
+            const cmd = `"${VENV_PYTHON}" "${SCAN_SCRIPT}" --api-url "${apiUrl}" health`;
+            const env = { ...process.env };
+            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: 5000, env });
+            const output = (stdout + stderr).trim();
+            console.log(output);
+
+            if (output.includes("✓") || output.includes("OK")) {
+              process.exit(0);
+            } else {
+              process.exit(1);
+            }
+          } catch (err: any) {
+            console.error(`❌ 连接失败: ${err.message}`);
+            console.error(`\n💡 请确保 skill-scanner-api 服务正在运行：`);
+            console.error(`   skill-scanner-api`);
+            process.exit(1);
+          }
+        });
+    },
+    { commands: ["skills-scanner"] }
+  );
+
+  api.logger.info("[skills-scanner] ✅ Plugin registered");
+}

package/openclaw.plugin.json

@@ -0,0 +1,60 @@
+{
+  "id": "skills-scanner",
+  "name": "Skills Scanner",
+  "description": "Security scanner for OpenClaw Skills to detect potential threats",
+  "version": "2026.3.10",
+  "author": "OpenClaw",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiUrl": {
+        "type": "string",
+        "description": "Scanner API service URL",
+        "default": "http://localhost:8000"
+      },
+      "scanDirs": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "List of directories to scan for Skills",
+        "default": []
+      },
+      "behavioral": {
+        "type": "boolean",
+        "description": "Enable behavioral analysis (slower but more accurate)",
+        "default": false
+      },
+      "useLLM": {
+        "type": "boolean",
+        "description": "Enable LLM-based semantic analysis",
+        "default": false
+      },
+      "policy": {
+        "type": "string",
+        "enum": ["strict", "balanced", "permissive"],
+        "description": "Scanning policy: strict (more false positives) / balanced (recommended) / permissive (may miss threats)",
+        "default": "balanced"
+      },
+      "preInstallScan": {
+        "type": "string",
+        "enum": ["on", "off"],
+        "description": "Enable pre-installation scanning (monitors directories for new Skills)",
+        "default": "on"
+      },
+      "onUnsafe": {
+        "type": "string",
+        "enum": ["quarantine", "delete", "warn"],
+        "description": "Action to take when unsafe Skill is detected: quarantine (recommended) / delete / warn",
+        "default": "quarantine"
+      },
+      "injectSecurityGuidance": {
+        "type": "boolean",
+        "description": "Inject Skills security guidance into system prompt (requires AI to scan before installing Skills)",
+        "default": true
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@pwddd/skills-scanner",
+  "version": "1.0.0",
+  "description": "OpenClaw Skills security scanner plugin - detect malicious code, data exfiltration, and prompt injection",
+  "type": "module",
+  "main": "./index.ts",
+  "author": "pwddd",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "security",
+    "scanner",
+    "skills",
+    "malware-detection"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw.git",
+    "directory": "extensions/skills-scanner"
+  },
+  "bugs": {
+    "url": "https://github.com/openclaw/openclaw/issues"
+  },
+  "homepage": "https://github.com/openclaw/openclaw/tree/main/extensions/skills-scanner#readme",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md",
+    "src/**/*.ts",
+    "skills/**/*"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.9"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/skills/skills-scanner/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: skills-scanner
+description: OpenClaw Skills 安全扫描工具，使用 Cisco AI Skill Scanner 检测恶意代码、数据窃取、提示注入等威胁。
+version: 1.0.0
+user-invocable: true
+metadata: {"openclaw": {"emoji": "🔍", "requires": {"bins": ["uv", "python3"]}, "install": [{"id": "uv-brew", "kind": "brew", "formula": "uv", "bins": ["uv"], "label": "安装 uv (macOS)", "os": ["darwin"]}, {"id": "uv-curl", "kind": "download", "url": "https://astral.sh/uv/install.sh", "label": "安装 uv (Linux)", "os": ["linux"]}]}}
+---
+
+# Skills 安全扫描工具 🔍
+
+OpenClaw Skills 安全扫描工具，检测恶意代码、数据窃取、提示注入等威胁。
+
+## 重要提示
+
+**在向用户展示扫描结果前，请务必：**
+1. 检查结果中是否包含英文内容（如 category、description、finding 详情等）
+2. 如果包含英文，将所有英文内容翻译为中文后再展示给用户
+3. 保持技术术语的准确性（如 CRITICAL、HIGH、MEDIUM、LOW 可保留或翻译为：严重、高危、中危、低危）
+4. 确保翻译后的内容清晰易懂，符合中文表达习惯
+
+示例翻译：
+- "Prompt injection detected" → "检测到提示注入"
+- "Unauthorized file access" → "未授权的文件访问"
+- "Data exfiltration attempt" → "数据窃取尝试"
+- "Malicious code execution" → "恶意代码执行"
+
+## 环境准备（首次使用）
+
+首次运行前，检查并安装依赖：
+
+```bash
+# 检查 uv 是否可用
+which uv || echo "请安装 uv: brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh"
+
+# 安装依赖到隔离虚拟环境
+uv venv {baseDir}/.venv --python 3.10 --quiet
+uv pip install --python {baseDir}/.venv/bin/python requests --quiet
+```
+
+安装只需执行一次。
+
+## 配置
+
+扫描器需要运行中的 API 服务。在 OpenClaw 配置中设置 API URL：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "skills-scanner": {
+        "config": {
+          "apiUrl": "http://localhost:8000"
+        }
+      }
+    }
+  }
+}
+```
+
+或直接调用时使用 `--api-url` 参数：
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 scan <路径>
+```
+
+---
+
+## 单个 Skill 扫描
+
+**触发词**: "扫描 skill"、"检查这个 skill"、"安全检查 [路径]"
+
+### 基础扫描（推荐，速度快）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径>
+```
+
+### 详细模式（显示所有发现）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径> --detailed
+```
+
+### 深度扫描（加入行为分析）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径> --detailed --behavioral
+```
+
+### 最强扫描（加入 LLM 语义分析）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径> --detailed --behavioral --llm
+```
+
+---
+
+## 批量扫描
+
+**触发词**: "批量扫描"、"扫描所有 skills"、"检查 skills 目录"
+
+### 扫描指定目录下的所有 Skills
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch <目录路径>
+```
+
+### 递归扫描（含子目录）
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch <目录路径> --recursive
+```
+
+### 批量扫描并输出 JSON 报告
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch <目录路径> --detailed --json /tmp/scan-report.json
+```
+
+### 常用目录示例
+
+扫描 OpenClaw 默认 skills 目录：
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch ~/.openclaw/skills
+```
+
+扫描 workspace skills：
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch ~/.openclaw/workspace/skills --recursive
+```
+
+---
+
+## 健康检查
+
+检查 API 服务是否运行：
+
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} health
+```
+
+---
+
+## 结果解读
+
+| 状态 | 含义 |
+|------|------|
+| ✅ 安全 | 未检测到 HIGH/CRITICAL 问题，可正常使用 |
+| ⚠️ 需关注 | 存在 LOW/MEDIUM 问题，建议人工复核 |
+| ❌ 发现问题 | 存在 HIGH/CRITICAL 威胁，**强烈建议不要安装** |
+
+### 严重级别说明
+
+- **CRITICAL**: 主动利用尝试（数据窃取、代码注入）
+- **HIGH**: 危险模式（提示注入、未授权访问）
+- **MEDIUM**: 可疑行为（未声明的能力、误导性描述）
+- **LOW**: 轻微风险，需人工判断
+
+---
+
+## 参数说明
+
+| 参数 | 说明 |
+|------|------|
+| `--api-url <url>` | API 服务地址（默认: http://localhost:8000） |
+| `--detailed` | 显示每条 finding 的完整详情 |
+| `--behavioral` | 启用 AST 数据流分析（更准确，稍慢） |
+| `--llm` | 启用 LLM 语义分析（最准确，需 API 支持） |
+| `--recursive` | 批量扫描时递归子目录 |
+| `--json <文件>` | 将结果保存为 JSON 文件 |
+| `--policy <strict\|balanced\|permissive>` | 扫描策略（默认: balanced） |
+
+---
+
+## 注意事项
+
+- **扫描结果不等于安全保证**。`is_safe=True` 表示未检测到已知威胁模式，不代表 skill 绝对安全。
+- 扫描使用静态分析，不会执行任何 skill 中的代码。
+- 退出码 `0` 表示安全，`1` 表示存在问题（便于 CI/CD 集成）。
+- `{apiUrl}` 占位符会自动替换为插件配置中的 API URL。