@pwddd/skills-scanner 1.0.0-beta.1

package/src/rate-limiter.ts

@@ -0,0 +1,102 @@
+/**
+ * Rate limiter module
+ *
+ * Prevents API overload by limiting request rate
+ */
+
+export class RateLimiter {
+  private requests: number[] = [];
+  private maxPerMinute: number;
+  private maxPerHour: number;
+
+  constructor(maxPerMinute = 60, maxPerHour = 1000) {
+    this.maxPerMinute = maxPerMinute;
+    this.maxPerHour = maxPerHour;
+  }
+
+  /**
+   * Acquire permission to make a request
+   * Waits if rate limit is exceeded
+   */
+  async acquire(): Promise<void> {
+    const now = Date.now();
+
+    // Remove requests older than 1 hour
+    this.requests = this.requests.filter((t) => now - t < 60 * 60 * 1000);
+
+    // Check hourly limit
+    if (this.requests.length >= this.maxPerHour) {
+      const oldestRequest = this.requests[0];
+      const waitTime = 60 * 60 * 1000 - (now - oldestRequest);
+      await this.sleep(waitTime);
+      return this.acquire(); // Retry after waiting
+    }
+
+    // Check per-minute limit
+    const recentRequests = this.requests.filter((t) => now - t < 60 * 1000);
+    if (recentRequests.length >= this.maxPerMinute) {
+      const oldestRecent = recentRequests[0];
+      const waitTime = 60 * 1000 - (now - oldestRecent) + 100; // Add 100ms buffer
+      await this.sleep(waitTime);
+      return this.acquire(); // Retry after waiting
+    }
+
+    // Record this request
+    this.requests.push(now);
+  }
+
+  /**
+   * Try to acquire without waiting
+   * Returns false if rate limit exceeded
+   */
+  tryAcquire(): boolean {
+    const now = Date.now();
+
+    // Remove old requests
+    this.requests = this.requests.filter((t) => now - t < 60 * 60 * 1000);
+
+    // Check limits
+    const recentRequests = this.requests.filter((t) => now - t < 60 * 1000);
+    if (
+      this.requests.length >= this.maxPerHour ||
+      recentRequests.length >= this.maxPerMinute
+    ) {
+      return false;
+    }
+
+    // Record this request
+    this.requests.push(now);
+    return true;
+  }
+
+  /**
+   * Get current rate limit status
+   */
+  getStatus(): {
+    requestsLastMinute: number;
+    requestsLastHour: number;
+    maxPerMinute: number;
+    maxPerHour: number;
+  } {
+    const now = Date.now();
+    const recentRequests = this.requests.filter((t) => now - t < 60 * 1000);
+
+    return {
+      requestsLastMinute: recentRequests.length,
+      requestsLastHour: this.requests.length,
+      maxPerMinute: this.maxPerMinute,
+      maxPerHour: this.maxPerHour,
+    };
+  }
+
+  /**
+   * Reset rate limiter
+   */
+  reset(): void {
+    this.requests = [];
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/report.ts

@@ -0,0 +1,128 @@
+/**
+ * Report generation module
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync, statSync } 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, PluginLogger } from "./types.js";
+
+export async function buildDailyReport(
+  dirs: string[],
+  behavioral: boolean,
+  apiUrl: string,
+  useLLM: boolean,
+  policy: string,
+  logger: PluginLogger
+): 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;
+
+    // Find all skills in directory
+    const skills: string[] = [];
+    try {
+      const entries = readdirSync(dir);
+      for (const entry of entries) {
+        const skillPath = join(dir, entry);
+        if (statSync(skillPath).isDirectory() && existsSync(join(skillPath, "SKILL.md"))) {
+          skills.push(skillPath);
+        }
+      }
+    } catch {
+      continue;
+    }
+
+    for (const skillPath of skills) {
+      try {
+        const res = await runScan("scan", skillPath, {
+          behavioral,
+          detailed: false,
+          apiUrl,
+          useLLM,
+          policy,
+        });
+
+        const name = basename(skillPath);
+        total++;
+
+        if (res.exitCode === 0) {
+          safe++;
+          allResults.push({
+            name,
+            path: skillPath,
+            is_safe: true,
+            max_severity: "NONE",
+            findings: 0,
+          });
+        } else {
+          unsafe++;
+          unsafeList.push(name);
+          allResults.push({
+            name,
+            path: skillPath,
+            is_safe: false,
+            max_severity: res.data?.max_severity || "UNKNOWN",
+            findings: res.data?.findings_count || 0,
+          });
+        }
+      } catch (err: any) {
+        errors++;
+        allResults.push({
+          name: basename(skillPath),
+          path: skillPath,
+          error: err.message,
+        });
+      }
+    }
+  }
+
+  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 === 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,230 @@
+/**
+ * Scanner module - calls skill-scanner-api via HTTP
+ */
+
+import { SkillScannerApiClient, type ScanResult as ApiScanResult } from "./api-client.js";
+import { recordScan } from "./metrics.js";
+import { createActionableError } from "./error-handler.js";
+
+export interface ScanOptions {
+  detailed?: boolean;
+  behavioral?: boolean;
+  recursive?: boolean;
+  jsonOut?: string;
+  apiUrl?: string;
+  useLLM?: boolean;
+  policy?: string;
+  timeoutMs?: number; // Scan timeout in milliseconds
+  stateDir?: string; // State directory for metrics
+}
+
+export interface ScanResult {
+  exitCode: number;
+  output: string;
+  data?: ApiScanResult;
+}
+
+export async function runScan(
+  mode: "scan" | "batch" | "clawhub" | "health",
+  target: string,
+  opts: ScanOptions = {}
+): Promise<ScanResult> {
+  const apiUrl = opts.apiUrl || "https://110.vemic.com/skills-scanner";
+  const timeoutMs = opts.timeoutMs || 180000; // Default 3 minutes
+  const policy = (opts.policy || "balanced") as "strict" | "balanced" | "permissive";
+  const client = new SkillScannerApiClient(apiUrl, timeoutMs);
+
+  const startTime = Date.now();
+  let success = false;
+
+  try {
+    if (mode === "health") {
+      const health = await client.health();
+      const lines = [];
+      if (health.status === "healthy") {
+        lines.push("✅ API 服务正常");
+        if (health.version) lines.push(`  版本：${health.version}`);
+        if (health.analyzers_available) {
+          lines.push(`  可用分析器：${health.analyzers_available.join(", ")}`);
+        }
+        return { exitCode: 0, output: lines.join("\n"), data: health as any };
+      } else {
+        lines.push(`❌ API 服务不可用：${apiUrl}`);
+        lines.push(`  错误：${health.error || "未知错误"}`);
+        return { exitCode: 1, output: lines.join("\n"), data: health as any };
+      }
+    }
+
+    if (mode === "clawhub") {
+      const result = await client.scanClawHub(target, {
+        policy: opts.policy as any,
+        useLLM: opts.useLLM,
+        useBehavioral: opts.behavioral,
+      });
+      const output = formatScanResult(result, opts.detailed);
+      return {
+        exitCode: result.is_safe ? 0 : 1,
+        output,
+        data: result,
+      };
+    }
+
+    if (mode === "scan") {
+      const result = await client.scanUpload(target, {
+        policy: policy as any,
+        useLLM: opts.useLLM,
+        useBehavioral: opts.behavioral,
+      });
+      const output = formatScanResult(result, opts.detailed);
+      success = true;
+
+      // Record metrics
+      if (opts.stateDir) {
+        recordScan(opts.stateDir, {
+          success: true,
+          durationMs: Date.now() - startTime,
+          policy,
+        });
+      }
+
+      return {
+        exitCode: result.is_safe ? 0 : 1,
+        output,
+        data: result,
+      };
+    }
+
+    if (mode === "batch") {
+      const { readdirSync, statSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { existsSync } = await import("node:fs");
+
+      if (!existsSync(target)) {
+        return { exitCode: 1, output: `路径不存在：${target}` };
+      }
+
+      const skills: string[] = [];
+      const entries = readdirSync(target);
+      for (const entry of entries) {
+        const skillPath = join(target, entry);
+        if (statSync(skillPath).isDirectory() && existsSync(join(skillPath, "SKILL.md"))) {
+          skills.push(skillPath);
+        }
+      }
+
+      if (skills.length === 0) {
+        return { exitCode: 1, output: `未找到任何 Skill：${target}` };
+      }
+
+      const results: ApiScanResult[] = [];
+      const lines: string[] = [];
+      let safe = 0;
+      let unsafe = 0;
+
+      for (let i = 0; i < skills.length; i++) {
+        const skillPath = skills[i];
+        lines.push(`[${i + 1}/${skills.length}] 正在扫描：${skillPath}`);
+
+        try {
+          const result = await client.scanUpload(skillPath, {
+            policy: opts.policy as any,
+            useLLM: opts.useLLM,
+            useBehavioral: opts.behavioral,
+          });
+          results.push(result);
+          if (result.is_safe) {
+            safe++;
+            lines.push(`  ✅ ${result.skill_name}: 安全`);
+          } else {
+            unsafe++;
+            lines.push(`  ❌ ${result.skill_name}: ${result.max_severity} (${result.findings_count} 个发现)`);
+          }
+        } catch (err: any) {
+          results.push({
+            skill_name: entry,
+            is_safe: false,
+            max_severity: "ERROR",
+            findings_count: 0,
+            error: err.message,
+          });
+          lines.push(`  ❌ ${entry}: 扫描失败 - ${err.message}`);
+        }
+      }
+
+      lines.push("");
+      lines.push(`批量扫描完成：${safe} 安全，${unsafe} 问题`);
+
+      if (opts.detailed && unsafe > 0) {
+        lines.push("");
+        lines.push("问题 Skills:");
+        for (const r of results.filter((r) => !r.is_safe)) {
+          lines.push(`  • ${r.skill_name} [${r.max_severity}] - ${r.findings_count} 条发现`);
+        }
+      }
+
+      return {
+        exitCode: unsafe === 0 ? 0 : 1,
+        output: lines.join("\n"),
+      };
+    }
+
+    return { exitCode: 1, output: `未知模式：${mode}` };
+  } catch (err: any) {
+    // Record failed scan
+    if (opts.stateDir && mode !== "health") {
+      recordScan(opts.stateDir, {
+        success: false,
+        durationMs: Date.now() - startTime,
+        policy,
+      });
+    }
+
+    // Create actionable error message
+    const errorMessage = createActionableError(
+      mode === "health" ? "健康检查" : "扫描操作",
+      err,
+      {
+        apiUrl,
+        path: target,
+        mode,
+        policy,
+      }
+    );
+
+    return {
+      exitCode: 1,
+      output: errorMessage,
+    };
+  }
+}
+
+/**
+ * Format scan result for display
+ */
+function formatScanResult(result: ApiScanResult, detailed = false): string {
+  const lines: string[] = [];
+  const statusIcon = result.is_safe ? "✅" : "❌";
+
+  lines.push(`${statusIcon} ${result.skill_name}`);
+  lines.push(`  严重性：${result.max_severity}`);
+  lines.push(`  发现数：${result.findings_count}`);
+
+  if (detailed && result.findings && result.findings.length > 0) {
+    lines.push("");
+    lines.push("发现详情:");
+    for (let i = 0; i < Math.min(result.findings.length, 10); i++) {
+      const finding = result.findings[i];
+      lines.push(`  ${i + 1}. [${finding.severity}] ${finding.category}`);
+      lines.push(`     ${finding.description}`);
+      if (finding.file) {
+        lines.push(`     文件：${finding.file}${finding.line ? `:${finding.line}` : ""}`);
+      }
+    }
+
+    if (result.findings.length > 10) {
+      lines.push(`  ... 还有 ${result.findings.length - 10} 条发现`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/state.ts

@@ -0,0 +1,136 @@
+/**
+ * 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";
+import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
+
+// Current state schema version
+const CURRENT_STATE_VERSION = 2;
+
+// Legacy fallback path (used when runtime is not available)
+const LEGACY_STATE_DIR = join(os.homedir(), ".openclaw", "skills-scanner");
+
+/**
+ * Get state directory path using official OpenClaw API
+ */
+export function getStateDir(runtime?: PluginRuntime): string {
+  if (runtime?.state?.resolveStateDir) {
+    const stateDir = runtime.state.resolveStateDir();
+    return join(stateDir, "skills-scanner");
+  }
+  // Fallback to legacy path
+  return LEGACY_STATE_DIR;
+}
+
+/**
+ * Get state file path
+ */
+export function getStateFile(runtime?: PluginRuntime): string {
+  return join(getStateDir(runtime), "state.json");
+}
+
+/**
+ * Migrate state from old versions to current version
+ */
+function migrateState(state: any): ScanState {
+  const version = state.version || 1;
+
+  if (version === CURRENT_STATE_VERSION) {
+    return state;
+  }
+
+  // Migration from v1 to v2
+  if (version === 1) {
+    // v1 didn't have version field or lastShutdownAt
+    return {
+      ...state,
+      version: 2,
+      lastShutdownAt: undefined,
+    };
+  }
+
+  // Unknown version - return as-is with current version
+  return {
+    ...state,
+    version: CURRENT_STATE_VERSION,
+  };
+}
+
+export function loadState(runtime?: PluginRuntime): ScanState {
+  try {
+    const stateFile = getStateFile(runtime);
+    const rawState = JSON.parse(readFileSync(stateFile, "utf-8"));
+    return migrateState(rawState);
+  } catch {
+    return { version: CURRENT_STATE_VERSION };
+  }
+}
+
+export function saveState(s: ScanState, runtime?: PluginRuntime): void {
+  const stateDir = getStateDir(runtime);
+  const stateFile = getStateFile(runtime);
+
+  // Ensure version is set
+  const stateWithVersion = {
+    ...s,
+    version: CURRENT_STATE_VERSION,
+  };
+
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(stateFile, JSON.stringify(stateWithVersion, null, 2));
+}
+
+export function isFirstRun(cfg: ScannerConfig, runtime?: PluginRuntime): boolean {
+  const state = loadState(runtime) 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(runtime?: PluginRuntime): void {
+  const state = loadState(runtime) as any;
+  saveState({ ...state, configReviewed: true }, runtime);
+}
+
+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 for backward compatibility
+export { LEGACY_STATE_DIR as STATE_DIR };
+export function STATE_FILE(runtime?: PluginRuntime): string {
+  return getStateFile(runtime);
+}

package/src/structured-logger.ts

@@ -0,0 +1,97 @@
+/**
+ * Structured logging utilities
+ */
+
+import type { PluginLogger } from "./types.js";
+
+export interface LogContext {
+  module?: string;
+  action?: string;
+  duration?: number;
+  [key: string]: any;
+}
+
+/**
+ * Log with structured context
+ */
+export function logInfo(
+  logger: PluginLogger,
+  message: string,
+  context?: LogContext
+): void {
+  if (context) {
+    logger.info(message, context);
+  } else {
+    logger.info(message);
+  }
+}
+
+export function logDebug(
+  logger: PluginLogger,
+  message: string,
+  context?: LogContext
+): void {
+  if (context) {
+    logger.debug(message, context);
+  } else {
+    logger.debug(message);
+  }
+}
+
+export function logWarn(
+  logger: PluginLogger,
+  message: string,
+  context?: LogContext
+): void {
+  if (context) {
+    logger.warn(message, context);
+  } else {
+    logger.warn(message);
+  }
+}
+
+export function logError(
+  logger: PluginLogger,
+  message: string,
+  error?: Error,
+  context?: LogContext
+): void {
+  const errorContext = {
+    ...context,
+    error: error?.message,
+    stack: error?.stack,
+  };
+  logger.error(message, errorContext);
+}
+
+/**
+ * Log operation with timing
+ */
+export async function logOperation<T>(
+  logger: PluginLogger,
+  operation: string,
+  fn: () => Promise<T>,
+  context?: LogContext
+): Promise<T> {
+  const startTime = Date.now();
+  logDebug(logger, `${operation} started`, context);
+
+  try {
+    const result = await fn();
+    const duration = Date.now() - startTime;
+    logInfo(logger, `${operation} completed`, {
+      ...context,
+      duration,
+      success: true,
+    });
+    return result;
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+    logError(logger, `${operation} failed`, error, {
+      ...context,
+      duration,
+      success: false,
+    });
+    throw error;
+  }
+}