@pwddd/skills-scanner 1.0.0-beta.1

package/src/api-client.ts

@@ -0,0 +1,245 @@
+/**
+ * API client module - direct HTTP calls to skill-scanner-api
+ */
+
+import { createReadStream, createWriteStream, existsSync, readdirSync, statSync } from "node:fs";
+import { join, basename, relative } from "node:path";
+import { tmpdir } from "node:os";
+import { pipeline } from "node:stream/promises";
+import { createWriteStream as createZipStream } from "node:fs";
+import archiver from "archiver";
+
+export interface ScanResult {
+  skill_name: string;
+  is_safe: boolean;
+  max_severity: string;
+  findings_count: number;
+  findings?: Array<{
+    severity: string;
+    category: string;
+    description: string;
+    file?: string;
+    line?: number;
+  }>;
+  scan_time?: number;
+  error?: string;
+}
+
+export interface HealthResult {
+  status: "healthy" | "unhealthy";
+  version?: string;
+  analyzers_available?: string[];
+  error?: string;
+}
+
+export interface ScanOptions {
+  policy?: "strict" | "balanced" | "permissive";
+  useLLM?: boolean;
+  useBehavioral?: boolean;
+  useZipVirus?: boolean;
+  enableMeta?: boolean;
+}
+
+export class SkillScannerApiClient {
+  private baseUrl: string;
+  private timeout: number;
+
+  constructor(baseUrl: string, timeout = 180000) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.timeout = timeout;
+  }
+
+  /**
+   * Health check
+   */
+  async health(): Promise<HealthResult> {
+    try {
+      const response = await fetch(`${this.baseUrl}/health`, {
+        method: "GET",
+        signal: AbortSignal.timeout(5000),
+      });
+
+      if (!response.ok) {
+        return {
+          status: "unhealthy",
+          error: `HTTP ${response.status}: ${response.statusText}`,
+        };
+      }
+
+      const data = await response.json();
+      return {
+        status: "healthy",
+        version: data.version,
+        analyzers_available: data.analyzers_available,
+      };
+    } catch (err: any) {
+      return {
+        status: "unhealthy",
+        error: err.message || "Connection failed",
+      };
+    }
+  }
+
+  /**
+   * Scan a local skill by uploading as ZIP
+   */
+  async scanUpload(skillPath: string, options: ScanOptions = {}): Promise<ScanResult> {
+    const zipPath = await this.createZip(skillPath);
+
+    try {
+      const formData = new FormData();
+      const zipBlob = await this.readFileAsBlob(zipPath);
+      formData.append("file", zipBlob, `${basename(skillPath)}.zip`);
+      formData.append("policy", options.policy || "balanced");
+      formData.append("use_llm", String(options.useLLM || false));
+      formData.append("use_behavioral", String(options.useBehavioral || false));
+      formData.append("use_zip_virus", String(options.useZipVirus !== false));
+      formData.append("enable_meta", String(options.enableMeta !== false));
+
+      const response = await fetch(`${this.baseUrl}/scan-upload`, {
+        method: "POST",
+        body: formData,
+        signal: AbortSignal.timeout(this.timeout),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`HTTP ${response.status}: ${errorText}`);
+      }
+
+      return await response.json();
+    } finally {
+      // Cleanup temp zip
+      try {
+        const fs = await import("node:fs/promises");
+        await fs.unlink(zipPath);
+      } catch {}
+    }
+  }
+
+  /**
+   * Scan a ClawHub skill by URL
+   */
+  async scanClawHub(clawhubUrl: string, options: ScanOptions = {}): Promise<ScanResult> {
+    const body = {
+      clawhub_url: clawhubUrl,
+      policy: options.policy || "balanced",
+      use_llm: options.useLLM || false,
+      use_behavioral: options.useBehavioral !== false, // default true for clawhub
+      llm_provider: "anthropic",
+      use_virustotal: false,
+      use_aidefense: false,
+      use_trigger: false,
+      use_zip_virus: options.useZipVirus !== false,
+      enable_meta: options.enableMeta !== false,
+    };
+
+    const response = await fetch(`${this.baseUrl}/scan-clawhub`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(this.timeout),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`HTTP ${response.status}: ${errorText}`);
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Create a ZIP file from a directory
+   */
+  private async createZip(sourceDir: string): Promise<string> {
+    const { mkdtemp, rm } = await import("node:fs/promises");
+    const tmpDir = await mkdtemp(join(tmpdir(), "skills-scanner-"));
+    const zipPath = join(tmpDir, `${basename(sourceDir)}.zip`);
+
+    return new Promise((resolve, reject) => {
+      const output = createZipStream(zipPath);
+      const archive = archiver("zip", { zlib: { level: 9 } });
+
+      output.on("close", () => resolve(zipPath));
+      archive.on("error", reject);
+
+      archive.pipe(output);
+
+      // Add all files from source directory
+      const addFiles = (dir: string, baseDir: string) => {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+          const fullPath = join(dir, entry);
+          const stat = statSync(fullPath);
+
+          if (stat.isDirectory()) {
+            addFiles(fullPath, baseDir);
+          } else if (stat.isFile()) {
+            const relativePath = relative(baseDir, fullPath);
+            archive.file(fullPath, { name: join(basename(sourceDir), relativePath) });
+          }
+        }
+      };
+
+      addFiles(sourceDir, sourceDir);
+      archive.finalize();
+    });
+  }
+
+  /**
+   * Read file as Blob for FormData
+   */
+  private async readFileAsBlob(filePath: string): Promise<Blob> {
+    const { readFile } = await import("node:fs/promises");
+    const buffer = await readFile(filePath);
+    return new Blob([buffer], { type: "application/zip" });
+  }
+}
+
+/**
+ * Format scan result for display
+ */
+export function formatScanResult(result: ScanResult, 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");
+}
+
+/**
+ * Format health check result
+ */
+export function formatHealthResult(result: HealthResult): string {
+  if (result.status === "healthy") {
+    const lines = ["✅ API 服务正常"];
+    if (result.version) lines.push(`  版本: ${result.version}`);
+    if (result.analyzers_available) {
+      lines.push(`  可用分析器: ${result.analyzers_available.join(", ")}`);
+    }
+    return lines.join("\n");
+  } else {
+    return `❌ API 服务不可用\n  错误: ${result.error || "未知错误"}`;
+  }
+}

package/src/before-install-hook.ts

@@ -0,0 +1,241 @@
+/**
+ * before_install hook handler
+ *
+ * 这个模块实现了关键的安全门禁，在 Skill/Plugin 安装前进行拦截。
+ */
+
+import { runScan } from "./scanner.js";
+import type { PluginLogger } from "./types.js";
+
+export interface BeforeInstallEvent {
+  targetType: "skill" | "plugin";
+  targetName: string;
+  sourcePath: string;
+  sourcePathKind: "file" | "directory";
+  origin?: string;
+  request: {
+    kind: string;
+    mode: string;
+    requestedSpecifier?: string;
+  };
+  builtinScan: {
+    status: "ok" | "error";
+    scannedFiles: number;
+    critical: number;
+    warn: number;
+    info: number;
+    findings: Array<{
+      severity: "critical" | "warn" | "info";
+      ruleId: string;
+      file: string;
+      line: number;
+      message: string;
+    }>;
+    error?: string;
+  };
+  skill?: {
+    installId: string;
+    installSpec: any;
+  };
+  plugin?: {
+    pluginId: string;
+    contentType: "bundle" | "package" | "file";
+    packageName?: string;
+    manifestId?: string;
+    version?: string;
+    extensions: string[];
+  };
+}
+
+export interface BeforeInstallResult {
+  findings?: Array<{
+    severity: "critical" | "warn" | "info";
+    ruleId: string;
+    file: string;
+    line: number;
+    message: string;
+  }>;
+  block?: boolean;
+  blockReason?: string;
+}
+
+export interface BeforeInstallHandlerOptions {
+  apiUrl: string;
+  behavioral: boolean;
+  useLLM: boolean;
+  policy: "strict" | "balanced" | "permissive";
+  logger: PluginLogger;
+  enabled: boolean;
+  timeoutMs?: number; // Scan timeout in milliseconds (default: 30000)
+}
+
+/**
+ * 处理 before_install hook 事件（带超时控制）
+ *
+ * 这是关键的安全门禁，防止不安全的 Skills/Plugins 被安装。
+ * 在内置扫描器之后、安装继续之前运行。
+ */
+export async function handleBeforeInstall(
+  event: BeforeInstallEvent,
+  options: BeforeInstallHandlerOptions
+): Promise<BeforeInstallResult> {
+  const timeoutMs = options.timeoutMs || 30000; // Default 30 seconds
+
+  // Wrap the scan in a timeout promise
+  return Promise.race([
+    performScan(event, options),
+    new Promise<BeforeInstallResult>((_, reject) =>
+      setTimeout(() => reject(new Error("Scan timeout")), timeoutMs)
+    ),
+  ]).catch((err: any) => {
+    options.logger.error("[before_install] Scan failed or timed out", {
+      error: err.message,
+      targetName: event.targetName,
+      timeoutMs,
+    });
+
+    // On timeout or error, allow installation but log warning
+    return {
+      block: false,
+      findings: [
+        {
+          severity: "warn",
+          ruleId: "scan-timeout",
+          file: event.sourcePath,
+          line: 0,
+          message: `扫描超时或失败: ${err.message}`,
+        },
+      ],
+    };
+  });
+}
+
+/**
+ * Perform the actual scan (extracted for timeout handling)
+ */
+async function performScan(
+  event: BeforeInstallEvent,
+  options: BeforeInstallHandlerOptions
+): Promise<BeforeInstallResult> {
+  const { targetType, targetName, sourcePath, builtinScan } = event;
+  const { apiUrl, behavioral, useLLM, policy, logger, enabled } = options;
+
+  // 如果 hook 被禁用，跳过
+  if (!enabled) {
+    logger.debug(`[安装前拦截] Hook 已禁用，允许安装 ${targetName}`);
+    return { block: false };
+  }
+
+  // 只扫描 Skills（让内置扫描器处理 Plugins）
+  if (targetType !== "skill") {
+    logger.debug(`[安装前拦截] 跳过 ${targetType}: ${targetName}`);
+    return { block: false };
+  }
+
+  logger.info(`[安装前拦截] 🔍 拦截 Skill 安装: ${targetName}`);
+  logger.info(`[安装前拦截]    来源: ${sourcePath}`);
+  logger.info(`[安装前拦截]    内置扫描: ${builtinScan.status} (${builtinScan.critical} 严重, ${builtinScan.warn} 警告)`);
+
+  // 首先检查内置扫描结果
+  if (builtinScan.status === "error") {
+    logger.warn(`[安装前拦截] ❌ ${targetName} 内置扫描失败`);
+    return {
+      block: true,
+      blockReason: `内置安全扫描失败: ${builtinScan.error || "未知错误"}`
+    };
+  }
+
+  // 如果内置扫描发现严重问题，立即阻止
+  if (builtinScan.critical > 0) {
+    logger.warn(`[安装前拦截] ❌ 内置扫描发现 ${builtinScan.critical} 个严重问题`);
+    return {
+      block: true,
+      blockReason: `内置扫描器检测到 ${builtinScan.critical} 个严重安全问题`,
+      findings: builtinScan.findings
+    };
+  }
+
+  // 运行增强扫描
+  try {
+    logger.info(`[安装前拦截] 🔬 正在运行增强安全扫描...`);
+
+    const scanResult = await runScan("scan", sourcePath, {
+      behavioral,
+      useLLM,
+      policy,
+      apiUrl,
+      detailed: true
+    });
+
+    if (scanResult.exitCode === 0) {
+      logger.info(`[安装前拦截] ✅ ${targetName} 通过安全扫描`);
+
+      // 如果内置扫描有警告，添加信息性发现
+      if (builtinScan.warn > 0) {
+        return {
+          block: false,
+          findings: builtinScan.findings.filter(f => f.severity === "warn")
+        };
+      }
+
+      return { block: false };
+    }
+
+    // 扫描失败 - 阻止安装
+    const severity = scanResult.data?.max_severity || "未知";
+    const findingsCount = scanResult.data?.findings || 0;
+
+    logger.warn(`[安装前拦截] ❌ ${targetName} 未通过安全扫描`);
+    logger.warn(`[安装前拦截]    严重性: ${severity}, 发现数: ${findingsCount}`);
+
+    return {
+      block: true,
+      blockReason: [
+        `Skills Scanner 在 "${targetName}" 中检测到安全威胁`,
+        `严重性: ${severity}`,
+        `发现数: ${findingsCount}`,
+        ``,
+        `运行 '/skills-scanner scan ${sourcePath} --detailed' 查看详细信息。`
+      ].join("\n"),
+      findings: [{
+        severity: "critical",
+        ruleId: "skills-scanner-enhanced",
+        file: sourcePath,
+        line: 0,
+        message: `增强扫描检测到 ${findingsCount} 个安全问题，最高严重性: ${severity}`
+      }]
+    };
+
+  } catch (error: any) {
+    // 扫描因错误失败 - 根据策略决定
+    logger.error(`[安装前拦截] ⚠️  ${targetName} 扫描错误: ${error.message}`);
+
+    // 在严格模式下，扫描错误时阻止
+    if (policy === "strict") {
+      return {
+        block: true,
+        blockReason: `安全扫描失败: ${error.message}。由于严格策略，已阻止安装。`,
+        findings: [{
+          severity: "warn",
+          ruleId: "scan-error",
+          file: sourcePath,
+          line: 0,
+          message: `扫描错误: ${error.message}`
+        }]
+      };
+    }
+
+    // 在平衡/宽松模式下，允许但警告
+    logger.warn(`[安装前拦截] ⚠️  尽管扫描错误，仍允许 ${targetName} (策略: ${policy})`);
+    return {
+      block: false,
+      findings: [{
+        severity: "warn",
+        ruleId: "scan-error",
+        file: sourcePath,
+        line: 0,
+        message: `安全扫描遇到错误: ${error.message}。请谨慎使用。`
+      }]
+    };
+  }
+}

package/src/cache.ts

@@ -0,0 +1,138 @@
+/**
+ * Scan result cache module
+ *
+ * Caches scan results to avoid re-scanning unchanged files
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+
+export interface CachedScanResult {
+  fileHash: string;
+  mtime: number;
+  isSafe: boolean;
+  severity: string;
+  findingsCount: number;
+  cachedAt: string;
+}
+
+export class ScanResultCache {
+  private cache = new Map<string, CachedScanResult>();
+  private maxEntries = 1000;
+  private maxAgeMs = 24 * 60 * 60 * 1000; // 24 hours
+
+  /**
+   * Get cached result if file hasn't changed
+   */
+  get(filePath: string): CachedScanResult | null {
+    try {
+      const cached = this.cache.get(filePath);
+      if (!cached) return null;
+
+      // Check if file has been modified
+      const stats = statSync(filePath);
+      if (stats.mtimeMs !== cached.mtime) {
+        this.cache.delete(filePath);
+        return null;
+      }
+
+      // Check if cache is too old
+      const age = Date.now() - new Date(cached.cachedAt).getTime();
+      if (age > this.maxAgeMs) {
+        this.cache.delete(filePath);
+        return null;
+      }
+
+      // Verify file hash
+      const currentHash = this.computeFileHash(filePath);
+      if (currentHash !== cached.fileHash) {
+        this.cache.delete(filePath);
+        return null;
+      }
+
+      return cached;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Store scan result in cache
+   */
+  set(
+    filePath: string,
+    result: {
+      isSafe: boolean;
+      severity: string;
+      findingsCount: number;
+    }
+  ): void {
+    try {
+      const stats = statSync(filePath);
+      const fileHash = this.computeFileHash(filePath);
+
+      this.cache.set(filePath, {
+        fileHash,
+        mtime: stats.mtimeMs,
+        isSafe: result.isSafe,
+        severity: result.severity,
+        findingsCount: result.findingsCount,
+        cachedAt: new Date().toISOString(),
+      });
+
+      this.pruneOldEntries();
+    } catch {
+      // Ignore cache errors
+    }
+  }
+
+  /**
+   * Compute file hash for verification
+   */
+  private computeFileHash(filePath: string): string {
+    const content = readFileSync(filePath);
+    return createHash("sha256").update(content).digest("hex");
+  }
+
+  /**
+   * Remove old entries to prevent memory bloat
+   */
+  private pruneOldEntries(): void {
+    if (this.cache.size <= this.maxEntries) return;
+
+    // Sort by cachedAt and remove oldest entries
+    const entries = Array.from(this.cache.entries());
+    entries.sort((a, b) => {
+      const timeA = new Date(a[1].cachedAt).getTime();
+      const timeB = new Date(b[1].cachedAt).getTime();
+      return timeA - timeB;
+    });
+
+    const toRemove = entries.slice(0, entries.length - this.maxEntries);
+    for (const [path] of toRemove) {
+      this.cache.delete(path);
+    }
+  }
+
+  /**
+   * Clear all cached results
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): {
+    size: number;
+    maxEntries: number;
+    maxAgeMs: number;
+  } {
+    return {
+      size: this.cache.size,
+      maxEntries: this.maxEntries,
+      maxAgeMs: this.maxAgeMs,
+    };
+  }
+}