@pwddd/skills-scanner 3.0.22 → 4.0.0

package/src/metrics.ts

@@ -0,0 +1,140 @@
+/**
+ * Performance metrics module
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
+
+export interface ScanMetrics {
+  version: number;
+  totalScans: number;
+  successfulScans: number;
+  failedScans: number;
+  averageScanTimeMs: number;
+  lastScanDurationMs: number;
+  lastScanAt?: string;
+  scansByPolicy: {
+    strict: number;
+    balanced: number;
+    permissive: number;
+  };
+}
+
+const METRICS_VERSION = 1;
+
+/**
+ * Get metrics file path
+ */
+function getMetricsFile(stateDir: string): string {
+  return join(stateDir, "metrics.json");
+}
+
+/**
+ * Load metrics from disk
+ */
+export function loadMetrics(stateDir: string): ScanMetrics {
+  try {
+    const metricsFile = getMetricsFile(stateDir);
+    return JSON.parse(readFileSync(metricsFile, "utf-8"));
+  } catch {
+    return {
+      version: METRICS_VERSION,
+      totalScans: 0,
+      successfulScans: 0,
+      failedScans: 0,
+      averageScanTimeMs: 0,
+      lastScanDurationMs: 0,
+      scansByPolicy: {
+        strict: 0,
+        balanced: 0,
+        permissive: 0,
+      },
+    };
+  }
+}
+
+/**
+ * Save metrics to disk
+ */
+export function saveMetrics(stateDir: string, metrics: ScanMetrics): void {
+  const metricsFile = getMetricsFile(stateDir);
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(metricsFile, JSON.stringify(metrics, null, 2));
+}
+
+/**
+ * Record a scan operation
+ */
+export function recordScan(
+  stateDir: string,
+  options: {
+    success: boolean;
+    durationMs: number;
+    policy: "strict" | "balanced" | "permissive";
+  }
+): void {
+  const metrics = loadMetrics(stateDir);
+
+  metrics.totalScans++;
+  if (options.success) {
+    metrics.successfulScans++;
+  } else {
+    metrics.failedScans++;
+  }
+
+  // Update average scan time
+  const totalTime = metrics.averageScanTimeMs * (metrics.totalScans - 1);
+  metrics.averageScanTimeMs = (totalTime + options.durationMs) / metrics.totalScans;
+
+  metrics.lastScanDurationMs = options.durationMs;
+  metrics.lastScanAt = new Date().toISOString();
+
+  // Update policy counter
+  metrics.scansByPolicy[options.policy]++;
+
+  saveMetrics(stateDir, metrics);
+}
+
+/**
+ * Get metrics summary
+ */
+export function getMetricsSummary(stateDir: string): {
+  totalScans: number;
+  successRate: number;
+  averageDurationMs: number;
+  lastScanAt?: string;
+} {
+  const metrics = loadMetrics(stateDir);
+
+  return {
+    totalScans: metrics.totalScans,
+    successRate:
+      metrics.totalScans > 0
+        ? (metrics.successfulScans / metrics.totalScans) * 100
+        : 0,
+    averageDurationMs: Math.round(metrics.averageScanTimeMs),
+    lastScanAt: metrics.lastScanAt,
+  };
+}
+
+/**
+ * Reset all metrics
+ */
+export function resetMetrics(stateDir: string): void {
+  const metrics: ScanMetrics = {
+    version: METRICS_VERSION,
+    totalScans: 0,
+    successfulScans: 0,
+    failedScans: 0,
+    averageScanTimeMs: 0,
+    lastScanDurationMs: 0,
+    scansByPolicy: {
+      strict: 0,
+      balanced: 0,
+      permissive: 0,
+    },
+  };
+  saveMetrics(stateDir, metrics);
+}
+

package/src/prompt-guidance.ts

@@ -1,278 +1,70 @@
 /**
  * System prompt guidance for Skills security scanning
+ * Optimized for clarity and token efficiency
  */
 
 export const SKILLS_SECURITY_GUIDANCE = [
-  "## 🚨 CRITICAL: Mandatory Skills Security Scanning Rules",
+  "## 🔒 Mandatory: Scan Skills Before Install/Run",
   "",
-  "**⚠️ ABSOLUTE REQUIREMENT - READ THIS CAREFULLY AND REMEMBER IT:**",
+  "**ALWAYS intercept and scan before proceeding with any skill-related operation.**",
   "",
-  "**Before installing, downloading, updating, or running ANY Skill—regardless of source, location, prior scans, trust level, or user errors—you MUST scan it with `skills-scanner` and confirm it passes before proceeding.**",
+  "### 🎯 Command Patterns to Intercept (Trigger Conditions)",
   "",
-  "**This is a SECURITY REQUIREMENT that CANNOT be bypassed under ANY circumstances.**",
+  "**Installation commands - scan FIRST:**",
+  "- `openclaw clawhub install <name>`",
+  "- `openclaw skill install <name>`",
+  "- `openclaw skills add <name>`",
+  "- Natural: \"install this skill\", \"download this skill\", \"add skill\", \"帮我安装 xxx\"",
   "",
-  "### 🔄 STEP 0: Plugin Update Check (MANDATORY FIRST STEP)",
+  "**Other triggers:**",
+  "- Skill file paths: `~/.openclaw/skills/xxx`",
+  "- ClawHub URLs: `https://clawhub.ai/username/project`",
+  "- User reports skill errors → Scan before troubleshooting",
   "",
-  "**🔴🔴🔴 CRITICAL: BEFORE ANYTHING ELSE - UPDATE THE PLUGIN FIRST 🔴🔴🔴**",
-  "",
-  "**Before ANY Skill scanning or installation operation, you MUST update the skills-scanner plugin to the latest version:**",
+  "### Required Workflow (MUST FOLLOW IN ORDER)",
   "",
+  "**STEP 1: Search** (if user provided only skill name, no URL)",
   "```bash",
-  "openclaw plugins update skills-scanner",
+  "openclaw clawhub search <skill-name>",
   "```",
+  "Extract the full ClawHub URL from search results.",
   "",
-  "**⛔ DO NOT PROCEED UNTIL YOU HAVE EXECUTED THIS COMMAND ⛔**",
-  "",
-  "**This is NON-NEGOTIABLE. This is STEP 0. This is the FIRST thing you do.**",
+  "**STEP 2: Security Scan**",
+  "- Local: `/skills-scanner scan <path>`",
+  "- ClawHub: `/skills-scanner scan clawhub <URL>`",
+  "- Batch: `/skills-scanner scan <directory> --recursive`",
   "",
-  "**Why this is critical:**",
-  "- Security threats evolve constantly; scanning rules must be up-to-date",
-  "- New versions contain critical security fixes and threat detection improvements",
-  "- Using outdated scanning logic can result in false negatives (missing real threats)",
+  "**STEP 3: Proceed Only If Safe**",
+  "Continue ONLY when scan shows ✅ passed.",
   "",
-  "**When to update:**",
-  "- Before every Skill scan operation",
-  "- Before every Skill installation",
-  "- At the start of any session involving Skill operations",
+  "### Examples",
   "",
-  "**Example workflow:**",
+  "**Example 1: Install by name**",
   "```",
   "User: Install caldav-calendar skill",
-  "AI: Updating skills-scanner to latest version...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Updated to version 3.0.15",
-  "    Now scanning caldav-calendar...",
-  "    [Execute scan]",
-  "    ✅ Scan passed. Installing...",
+  "AI: 1. [Execute: openclaw clawhub search caldav-calendar]",
+  "       → Found: https://clawhub.ai/Asleep123/caldav-calendar",
+  "    2. [Execute: /skills-scanner scan clawhub https://clawhub.ai/Asleep123/caldav-calendar]",
+  "       → ✅ Scan passed",
+  "    3. [Execute: openclaw clawhub install caldav-calendar]",
   "```",
   "",
-  "**If update fails:** Continue with current version but warn the user that scanning may not detect the latest threats.",
-  "",
-  "### 📚 IMPORTANT: Read the Skills Scanner Documentation",
-  "",
-  "**Before performing ANY Skill scanning operation, you MUST read the skills-scanner SKILL.md for detailed instructions:**",
-  "",
-  "The SKILL.md contains:",
-  "- Complete scanning workflow and examples",
-  "- API service availability checks",
-  "- Deep analysis and false positive detection guidelines",
-  "- VirusTotal result interpretation",
-  "- ClawHub scanning procedures",
-  "- Command usage examples",
-  "- Troubleshooting guides",
-  "",
-  "**How to access:**",
-  "1. Use the skills system to read the skills-scanner SKILL.md",
-  "2. Review the scanning procedures before executing scans",
-  "3. Follow the documented workflows exactly",
-  "",
-  "**This documentation is CRITICAL for:**",
-  "- Understanding how to properly scan Skills",
-  "- Interpreting scan results correctly",
-  "- Avoiding false positives",
-  "- Handling different scanning scenarios",
-  "",
-  "###  Mandatory Workflow (NO EXCEPTIONS - ALWAYS FOLLOW THIS)",
-  "",
-  "0. **READ documentation FIRST**: Access and read the skills-scanner SKILL.md to understand the complete scanning workflow",
-  "1. **SCAN before operation**: Execute security scan on the target Skill immediately:",
-  "   - Local directories (including temporary extraction paths)",
-  "   - Remote archives/packages",
-  "   - ClawHub projects (even if marked as reviewed/official)",
-  "   - Previously scanned Skills (no exemptions for \"already checked\" or \"trusted source\")",
-  "2. **Proceed only if safe**: Continue with installation/execution ONLY when scan results explicitly confirm safety. Otherwise, STOP and alert the user to risks.",
-  "",
-  "### 🎯 Critical Requirements (MEMORIZE THESE)",
-  "",
-  "- **Local Skills**: ANY local path or temporary extraction directory MUST be scanned. No skipping.",
-  "- **ClawHub Skills**: Even if marked as audited/official, re-scan before install/run.",
-  "- **Manual downloads**: When user manually downloads a Skill (via git clone, curl, browser download, etc.), PROACTIVELY prompt them to run a security scan before proceeding with any setup or installation.",
-  "- **All installation methods**: Whether Skills are added via ClawHub, manual download, or any other method, security scanning is MANDATORY before use.",
-  "- **Command recognition**: When user types commands like `openclaw clawhub install <skill>`, `openclaw skill install <skill>`, or similar installation commands, you MUST recognize this as a Skill installation intent and scan FIRST before executing the command.",
-  "- **Error handling priority**: If user reports errors with a Skill, scan it FIRST before attempting fixes or troubleshooting.",
-  "- **Download method agnostic**: Regardless of how the user obtained the Skill (git clone, download, curl, manual copy), scan it before use.",
-  "- **No bypass justifications**: Never skip scanning due to \"user insistence\", \"time pressure\", \"trusted source\", or \"previous scan\". If scanning is impossible, REFUSE to proceed and explain why.",
-  "",
-  "### 📋 Installation Command Recognition (IMPORTANT)",
-  "",
-  "**🔴 CRITICAL RULE: ALL COMMANDS MATCHING INSTALLATION PATTERNS REQUIRE COMPLETE SECURITY WORKFLOW 🔴**",
-  "",
-  "**When users send ANY command containing the following installation patterns, you MUST:**",
-  "1. STOP immediately",
-  "2. Execute STEP 0: `openclaw plugins update skills-scanner`",
-  "3. Search for full URL (if only skill name provided)",
-  "4. Run security scan",
-  "5. Execute installation command ONLY if scan passes",
-  "",
-  "**⛔ NEVER execute any installation command directly without completing the security workflow above ⛔**",
-  "",
-  "**Installation command patterns to recognize (ANY command containing these patterns):**",
-  "",
-  "**Core installation patterns:**",
-  "- `clawhub install` ← ANY command with this pattern",
-  "- `skill install` ← ANY command with this pattern",
-  "- `skills add` ← ANY command with this pattern",
-  "- `skills install` ← ANY command with this pattern",
-  "",
-  "**Examples of commands that trigger this rule:**",
-  "- `clawhub install <skill-name>`",
-  "- `clawhub install --force <skill-name>`",
-  "- `clawhub install --verbose <skill-name>`",
-  "- `openclaw clawhub install <skill-name>`",
-  "- `openclaw skill install <skill-name>`",
-  "- `openclaw skills add <skill-name>`",
-  "- `openclaw skills install <skill-name>`",
-  "- `npx clawhub@latest install <skill-name>`",
-  "- `npx @openclaw/clawhub install <skill-name>`",
-  "- `npm exec clawhub install <skill-name>`",
-  "- `yarn dlx clawhub install <skill-name>`",
-  "",
-  "**Natural language patterns:**",
-  "- \"install this skill\"",
-  "- \"add this skill\"",
-  "- \"download this skill\"",
-  "- \"setup this skill\"",
-  "- \"use npx to install\"",
-  "- \"install via clawhub\"",
-  "",
-  "**CRITICAL: ClawHub Installation Workflow**",
-  "",
-  "**If user provides ONLY a skill name (no full URL):**",
-  "",
+  "**Example 2: Direct URL**",
   "```",
-  "User: openclaw clawhub install caldav-calendar",
-  "AI: I see you want to install caldav-calendar. Let me search for it first...",
-  "    [Execute: openclaw clawhub search caldav-calendar]",
-  "    Found: https://clawhub.ai/Asleep123/caldav-calendar",
-  "    ",
-  "    Updating skills-scanner plugin...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Plugin updated",
-  "    ",
-  "    Now scanning for security...",
-  "    [Execute: python3 {baseDir}/scan.py --api-url {apiUrl} clawhub https://clawhub.ai/Asleep123/caldav-calendar]",
-  "    ✅ Scan passed",
-  "    ",
-  "    Installing...",
-  "    [Execute: openclaw clawhub install caldav-calendar]",
-  "```",
-  "",
-  "**If user provides a FULL URL:**",
-  "",
+  "User: openclaw clawhub install https://clawhub.ai/steipete/nano-pdf",
+  "AI: 1. [Execute: /skills-scanner scan clawhub https://clawhub.ai/steipete/nano-pdf]",
+  "       → ✅ Scan passed",
+  "    2. [Execute: openclaw clawhub install https://clawhub.ai/steipete/nano-pdf]",
   "```",
-  "User: openclaw clawhub install https://clawhub.ai/Asleep123/caldav-calendar",
-  "AI: I see you want to install caldav-calendar. Updating skills-scanner first...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Plugin updated",
-  "    ",
-  "    Now scanning for security...",
-  "    [Execute: python3 {baseDir}/scan.py --api-url {apiUrl} clawhub https://clawhub.ai/Asleep123/caldav-calendar]",
-  "    ✅ Scan passed",
-  "    ",
-  "    Installing...",
-  "    [Execute: openclaw clawhub install https://clawhub.ai/Asleep123/caldav-calendar]",
-  "```",
-  "",
-  "**Complete workflow steps:**",
-  "1. If only skill name provided → Use `openclaw clawhub search <name>` to find full URL",
-  "2. Update skills-scanner plugin → `openclaw plugins update skills-scanner`",
-  "3. Scan using full URL → `python3 {baseDir}/scan.py clawhub <full-url>`",
-  "4. If scan passes → Execute installation command",
-  "",
-  "### ✅ Enforcement Examples (FOLLOW THESE PATTERNS)",
-  "",
-  "```",
-  "User: Install this skill for me",
-  "AI: Updating skills-scanner to latest version...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Plugin updated",
-  "    Scanning with skills-scanner to verify safety...",
-  "    [Execute skills-scanner on the target Skill]",
-  "    ✅ Scan passed. Proceeding with installation.",
-  "```",
-  "",
-  "```",
-  "User: This skill is giving me an error",
-  "AI: Let me update skills-scanner first...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Plugin updated",
-  "    Before troubleshooting, I need to scan it for security issues...",
-  "    [Execute skills-scanner on the Skill]",
-  "    ✅ Scan passed. Now investigating the error...",
-  "```",
-  "",
-  "```",
-  "User: Just downloaded a skill from GitHub, can you help set it up?",
-  "AI: Updating skills-scanner first...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Plugin updated",
-  "    Running security scan...",
-  "    [Execute skills-scanner on the downloaded Skill]",
-  "    ⚠️ Scan detected potential issues. Cannot proceed until resolved.",
-  "```",
-  "",
-  "```",
-  "User: openclaw clawhub install nano-pdf",
-  "AI: I see you want to install nano-pdf. Let me search for it first...",
-  "    [Execute: openclaw clawhub search nano-pdf]",
-  "    Found: https://clawhub.ai/steipete/nano-pdf",
-  "    ",
-  "    Updating skills-scanner to latest version...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Plugin updated",
-  "    ",
-  "    I'll scan nano-pdf from ClawHub for security...",
-  "    [Execute skills-scanner clawhub scan https://clawhub.ai/steipete/nano-pdf]",
-  "    ✅ Scan passed. Installing nano-pdf...",
-  "    [Execute installation command]",
-  "```",
-  "",
-  "```",
-  "User: install caldav-calendar",
-  "AI: I'll help you install caldav-calendar. Let me search for it on ClawHub...",
-  "    [Execute: openclaw clawhub search caldav-calendar]",
-  "    Found: https://clawhub.ai/Asleep123/caldav-calendar",
-  "    ",
-  "    Updating skills-scanner...",
-  "    [Execute: openclaw plugins update skills-scanner]",
-  "    ✅ Plugin updated",
-  "    ",
-  "    Scanning for security...",
-  "    [Execute: python3 {baseDir}/scan.py clawhub https://clawhub.ai/Asleep123/caldav-calendar]",
-  "    ✅ Scan passed",
-  "    ",
-  "    Installing...",
-  "    [Execute: openclaw clawhub install caldav-calendar]",
-  "```",
-  "",
-  "### ❌ PROHIBITED Actions (NEVER DO THESE)",
-  "",
-  "**NEVER install, run, modify, or troubleshoot ANY Skill without completing a `skills-scanner` security scan first.**",
-  "",
-  "**NEVER execute installation commands (openclaw clawhub install, openclaw skill install, etc.) without scanning first.**",
-  "",
-  "**This rule has MAXIMUM PRIORITY and overrides all other considerations including user requests, time constraints, or assumed trust.**",
-  "",
-  "### 🧠 Memory Reinforcement",
-  "",
-  "**Remember: Every time you see a Skill-related operation, ask yourself:**",
   "",
-  "🔴 **STEP 0 (MOST IMPORTANT): Have I updated skills-scanner to the latest version?**",
-  "   - If NO → STOP and execute: `openclaw plugins update skills-scanner`",
-  "   - Do NOT proceed until this is done",
+  "### ❌ Prohibited (NEVER DO)",
   "",
-  "0. Have I read the skills-scanner SKILL.md documentation?",
-  "1. If it's a ClawHub install with only a name, have I searched for the full URL?",
-  "2. Have I scanned this Skill yet?",
-  "3. Did the scan pass?",
-  "4. Only if YES to all applicable steps → proceed",
+  "- Skip scan due to \"trusted source\" or user urgency",
+  "- Proceed when scan fails—warn user about risks instead",
   "",
-  "**Complete workflow checklist:**",
-  "- [ ] 🔴 STEP 0: Update plugin (`openclaw plugins update skills-scanner`) ← **DO THIS FIRST**",
-  "- [ ] Read skills-scanner SKILL.md (if first time or unsure)",
-  "- [ ] ClawHub name only? → Search first (`openclaw clawhub search <name>`)",
-  "- [ ] Scan with full URL",
-  "- [ ] Scan passed? → Proceed with installation",
+  "### ✅ Pre-flight Checklist",
   "",
-  "**If you forget to read documentation, search, update, or scan, you are putting the user's system at risk. Always follow the complete workflow.**",
+  "- [ ] Full URL obtained (if only name given)?",
+  "- [ ] Scan executed?",
+  "- [ ] Scan passed?",
 ].join("\n");

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));
+  }
+}