Ken-Chy129/clawhub-scanner

# clawhub-scanner [](https://www.npmjs.com/package/clawhub-scanner) [](https://nodejs.org/) [](LICENSE) [中文文档](./README_zh.md) ## 与 ClawHub 的关系 [ClawHub](https://clawhub.com) 内置了安全扫描功能，会在每个 Skill 触达用户之前进行审查。本软件包实现了相同的多层扫描逻辑，因此你可以在本地运行完全相同的检查 —— 在发布前发现问题，或将其集成到你自己的 CI/CD 流水线中： 1. **静态正则扫描** — 快速、离线的模式匹配，针对已知的恶意签名（危险的 exec、数据渗漏、加密挖矿、prompt 注入等） 2. **LLM 安全评估** — LLM-as-judge 评估器，从 5 个安全维度评估 Skill，检查 Skill 的实际行为与其声明的目的是否一致 3. **Prompt 注入检测** — 预扫描过滤器，捕获操纵 LLM 评估器本身的尝试 这不是一个通用的安全扫描器。它是专门为 ClawHub / OpenClaw 的 Skill 格式构建的，并理解 AI Agent 插件的特定威胁模型：即那些可以指示 AI Agent 执行 Shell 命令、访问凭据、读取文件以及通过网络发送数据的 Skill。 ## 功能特性 - **静态正则扫描** — 无需任何 API 密钥即可检测危险模式： - Shell 命令执行（`child_process`、`exec`、`spawn`） - 动态代码执行（`eval`、`new Function`） - 加密挖矿指标（`stratum+tcp`、`coinhive`、`xmrig`） - 数据渗漏（文件读取 + 网络发送） - 凭据收集（环境变量访问 + 网络发送） - 混淆代码（十六进制序列、长 base64 payload） - Markdown 中的 Prompt 注入模式 - 配置文件中的可疑 URL（URL 缩短器、原始 IP） - **LLM 安全评估** — 5 维度深度分析： - 目的与能力一致性 - 指令范围分析 - 安装机制风险 - 凭据比例性 - 持久化与权限评估 - **Prompt 注入检测** — 识别常见的注入模式： - "Ignore previous instructions"（忽略之前的指令） - "You are now a..."（你现在是一个...） - System Prompt 覆盖尝试 - 隐藏的 base64 代码块 - Unicode 控制字符 ## 安装 ``` # 全局安装 npm install -g clawhub-scanner # 或直接使用 npx npx clawhub-scanner --help # 或作为项目依赖安装 npm install clawhub-scanner ``` ## CLI 用法 ``` # 静态扫描（无需 API key） clawhub-scan --static ./my-skill # 完整扫描（静态 + LLM 评估） OPENAI_API_KEY=sk-xxx clawhub-scan ./my-skill # 一次扫描多个 skills clawhub-scan --static ./skill-a ./skill-b ./skill-c # JSON 输出（用于 CI/CD pipelines） clawhub-scan --static --json ./my-skill # 将结果保存到目录 clawhub-scan --static --output ./results ./my-skill # 使用自定义 LLM model clawhub-scan --model gpt-4o ./my-skill ``` ### CLI 选项 | Option | Description | |--------|-------------| | `--static` | 仅静态扫描（无 LLM，无需 API 密钥） | | `--json` | 以 JSON 格式输出结果 | | `--output ` | 将单独的 JSON 结果保存到目录 | | `--model ` | LLM 模型名称（默认：`gpt-5-mini`） | | `--api-key ` | OpenAI API 密钥（默认：`OPENAI_API_KEY` 环境变量） | ### 环境变量 | Variable | Description | |----------|-------------| | `OPENAI_API_KEY` | LLM 评估所需 | | `OPENAI_EVAL_MODEL` | 覆盖默认的 LLM 模型 | ## 库用法 ``` import { scanSkill, scanSkillContent, runStaticScan, detectInjectionPatterns, } from 'clawhub-scanner' // Scan a skill directory const result = await scanSkill('/path/to/skill', { staticOnly: true }) console.log(result.staticStatus) // 'clean' | 'suspicious' | 'malicious' console.log(result.staticScan.findings) // Array of findings // Scan raw content (no disk I/O) const scan = runStaticScan(skillMdContent, [ { path: 'helper.js', content: 'const { exec } = require("child_process")...' }, ]) // => { status: 'suspicious', reasonCodes: [...], findings: [...] } // Detect prompt injection patterns const signals = detectInjectionPatterns('Ignore all previous instructions') // => ['ignore-previous-instructions'] // Full scan with LLM evaluation const fullResult = await scanSkill('/path/to/skill', { apiKey: 'sk-xxx', model: 'gpt-4o', }) console.log(fullResult.verdict) // 'benign' | 'suspicious' | 'malicious' console.log(fullResult.confidence) // 'high' | 'medium' | 'low' ``` ### API 参考 #### `scanSkill(dirPath, options?)` → `Promise` 扫描一个 Skill 目录。如果未找到 `SKILL.md` 则返回 `null`。 #### `scanSkillContent(skillMd, files?, options?)` → `Promise` 从原始内容进行扫描，无需从磁盘读取。 #### `runStaticScan(skillMd, files)` → `StaticScanResult` 仅运行基于正则的静态分析。同步执行，无需 API 密钥。 #### `detectInjectionPatterns(text)` → `string[]` 检测文本内容中的 Prompt 注入模式。 ## 扫描结果格式 ``` { "skill": "my-skill", "timestamp": "2026-03-13T08:00:00.000Z", "staticScan": { "status": "suspicious", "reasonCodes": ["suspicious.dangerous_exec"], "findings": [ { "code": "suspicious.dangerous_exec", "severity": "critical", "file": "helper.js", "line": 5, "message": "Shell command execution detected.", "evidence": "exec('rm -rf /')" } ] }, "injectionSignals": [], "llmResult": { "verdict": "suspicious", "confidence": "high", "summary": "...", "dimensions": { ... }, "user_guidance": "..." } } ``` ## 原因代码 | Code | Severity | Description | |------|----------|-------------| | `suspicious.dangerous_exec` | critical | 通过 child_process 执行 Shell 命令 | | `suspicious.dynamic_code_execution` | critical | eval() 或 new Function() 的使用 | | `malicious.crypto_mining` | critical | 加密挖矿指标 | | `malicious.env_harvesting` | critical | 环境变量访问 + 网络发送 | | `suspicious.potential_exfiltration` | warn | 文件读取 + 网络发送 | | `suspicious.obfuscated_code` | warn | 混淆/编码的 payload | | `suspicious.prompt_injection_instructions` | warn | Markdown 中的 Prompt 注入 | | `suspicious.install_untrusted_source` | warn | URL 缩短器或原始 IP | ## 工作原理 — ClawHub 安全流水线 ``` ┌─────────────────────────────────────────────────────────┐ │ Skill Published │ │ (SKILL.md + code files) │ └─────────────────┬───────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Layer 1: Static Regex Scan │ │ ───────────────────────── │ │ • Pattern match against known malicious signatures │ │ • Check code files for dangerous APIs │ │ • Check configs for suspicious URLs │ │ • Check markdown for prompt injection │ │ Result: clean / suspicious / malicious │ └─────────────────┬───────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Layer 2: Prompt Injection Pre-filter │ │ ──────────────────────────────── │ │ • Detect "ignore previous instructions" patterns │ │ • Catch system prompt override attempts │ │ • Flag hidden base64 blocks & unicode control chars │ │ • Feed signals to LLM as adversarial context │ └─────────────────┬───────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ Layer 3: LLM-as-Judge Evaluation │ │ ──────────────────────────── │ │ 5-dimension coherence analysis: │ │ 1. Purpose ↔ Capability alignment │ │ 2. Instruction scope boundaries │ │ 3. Install mechanism risk │ │ 4. Credential proportionality │ │ 5. Persistence & privilege assessment │ │ │ │ Verdict: benign / suspicious / malicious │ │ + confidence level + plain-language user guidance │ └─────────────────────────────────────────────────────────┘ ``` 此扫描器的核心洞察是**一致性检测，而非恶意软件分类**。`child_process.exec()` 调用在部署类 Skill 中是正常的，但在 Markdown 格式化工具中则是可疑的。LLM 评估器理解上下文，它会问：“此能力是否属于这里？” ## 什么是 Skill？ **Skill** 是 AI Agent 的插件（例如 [Claude Code](https://claude.com/claude-code) 或 [OpenClaw](https://openclaw.com))）。每个 Skill 包含： - `SKILL.md` — 告诉 AI Agent 该做什么的指令 - 可选代码文件（`.js`、`.py`、`.sh` 等） - 可选元数据（YAML frontmatter），声明依赖项、环境变量、安装规范 Skill 功能强大 —— 但也具有危险性。它们可以指示 AI Agent 执行 Shell 命令、访问你的凭据、读取你的文件以及通过网络发送数据。**安装前务必扫描。** ## 相关项目 - [ClawHub](https://clawhub.com) — 运行此扫描器的 Skill 市场 - [OpenClaw](https://openclaw.com) — 开源 AI Agent 框架 - [anygen-skills](https://github.com/Ken-Chy129/anygen-skills) — 经此工具扫描的 AI Skill 集合 ## 许可证 MIT

标签：AI Agent安全, ClawHub, DevSecOps, DNS 反向解析, GNU通用公共许可证, LLM安全评估, MITM代理, Node.js, NPM包, OpenClaw, OSV-Scalibr, Petitpotam, 上游代理, 云安全监控, 凭据窃取检测, 加密挖矿检测, 发布前检查, 命令执行检测, 多平台, 安全扫描, 技能插件扫描, 数据泄露防护, 时序注入, 暗色界面, 本地安全检查, 正则匹配, 混淆代码检测, 网络探测, 自定义脚本, 零依赖, 静态分析