@pwddd/skills-scanner 1.0.3

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" | "clawhub",
+  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,71 @@
+/**
+ * State management module
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+import type { ScanState, ScannerConfig } from "./types.js";
+
+const STATE_DIR = join(os.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(/^~/, os.homedir());
+}
+
+export function defaultScanDirs(): string[] {
+  const dirs = [
+    join(os.homedir(), ".openclaw", "skills"),
+    join(os.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";

package/src/watcher.ts

@@ -0,0 +1,125 @@
+/**
+ * File watcher module for pre-installation scanning
+ */
+
+import { watch as fsWatch, existsSync, renameSync, rmSync } from "node:fs";
+import { join, basename } from "node:path";
+import { mkdirSync } from "node:fs";
+import { runScan } from "./scanner.js";
+import type { OnUnsafeAction } from "./types.js";
+
+export async function handleNewSkill(
+  skillPath: string,
+  onUnsafe: OnUnsafeAction,
+  behavioral: boolean,
+  apiUrl: string,
+  useLLM: boolean,
+  policy: string,
+  notifyFn: (msg: string) => void,
+  logger: any,
+  venvPython: string,
+  scanScript: string,
+  quarantineDir: string
+): Promise<void> {
+  if (!existsSync(join(skillPath, "SKILL.md"))) return;
+  
+  const name = basename(skillPath);
+  logger.info(`[skills-scanner] 🔍 检测到新 Skill，开始安装前扫描: ${name}`);
+  notifyFn(`🔍 检测到新 Skill \`${name}\`，正在安全扫描...`);
+
+  const res = await runScan(venvPython, scanScript, "scan", skillPath, {
+    behavioral,
+    detailed: true,
+    apiUrl,
+    useLLM,
+    policy,
+  });
+
+  if (res.exitCode === 0) {
+    notifyFn(`✅ \`${name}\` 安全检查通过，可以正常使用。`);
+    return;
+  }
+
+  let action = "";
+  try {
+    if (onUnsafe === "quarantine") {
+      mkdirSync(quarantineDir, { recursive: true });
+      const dest = join(quarantineDir, `${name}-${Date.now()}`);
+      renameSync(skillPath, dest);
+      action = `已移入隔离目录：\`${dest}\``;
+    } else if (onUnsafe === "delete") {
+      rmSync(skillPath, { recursive: true, force: true });
+      action = "已自动删除";
+    } else {
+      action = "仅警告，Skill 已保留（请谨慎使用）";
+    }
+  } catch (e: any) {
+    action = `处置失败：${e.message}`;
+  }
+
+  notifyFn(
+    [
+      `❌ *安全警告：\`${name}\` 未通过扫描*`,
+      `处置：${action}`,
+      "```",
+      res.output.slice(0, 600),
+      "```",
+    ].join("\n")
+  );
+}
+
+export function startWatcher(
+  dirs: string[],
+  onUnsafe: OnUnsafeAction,
+  behavioral: boolean,
+  apiUrl: string,
+  useLLM: boolean,
+  policy: string,
+  notifyFn: (msg: string) => void,
+  logger: any,
+  venvPython: string,
+  scanScript: string,
+  quarantineDir: string
+): () => void {
+  const timers = new Map<string, NodeJS.Timeout>();
+
+  const watchers = dirs.map((dir) => {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    logger.info(`[skills-scanner] 👁  监听目录：${dir}`);
+
+    return fsWatch(dir, { persistent: false }, (_evt, filename) => {
+      if (!filename) return;
+      const skillPath = join(dir, filename);
+      if (!existsSync(skillPath)) return;
+
+      const prev = timers.get(skillPath);
+      if (prev) clearTimeout(prev);
+      timers.set(
+        skillPath,
+        setTimeout(() => {
+          timers.delete(skillPath);
+          handleNewSkill(
+            skillPath,
+            onUnsafe,
+            behavioral,
+            apiUrl,
+            useLLM,
+            policy,
+            notifyFn,
+            logger,
+            venvPython,
+            scanScript,
+            quarantineDir
+          );
+        }, 500)
+      );
+    });
+  });
+
+  return () => {
+    watchers.forEach((w) => w.close());
+    timers.forEach((t) => clearTimeout(t));
+    timers.clear();
+    logger.info("[skills-scanner] 目录监听已停止");
+  };
+}