@pwddd/skills-scanner 3.0.3 → 3.0.4

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "skills-scanner",
   "name": "Skills Scanner",
   "description": "Security scanner for OpenClaw Skills to detect potential threats",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "author": "pwddd",
   "skills": ["./skills"],
   "configSchema": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pwddd/skills-scanner",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "OpenClaw Skills security scanner plugin - detect malicious code, data exfiltration, and prompt injection",
   "type": "module",
   "main": "./index.ts",

package/skills/skills-scanner/SKILL.md

@@ -23,6 +23,55 @@ OpenClaw Skills 安全扫描工具，检测恶意代码、数据窃取、提示
 
 **在向用户展示扫描结果前，请务必：**
 
+### 0. API 服务可用性检查 🔌
+
+**在执行任何扫描操作前，必须先检查 API 服务是否可用。如果服务不可用，跳过安全检查。**
+
+**检查方法**：
+```bash
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 health
+```
+
+**处理规则**：
+
+1. **服务可用**（返回 `✓` 或 `OK`）：
+   - 继续执行扫描操作
+   - 正常展示扫描结果
+
+2. **服务不可用**（连接失败、超时、错误响应）：
+   - ⚠️ **立即跳过安全检查**
+   - 向用户说明：
+     ```
+     ⚠️ Skills 安全扫描服务当前不可用，已跳过安全检查。
+     
+     如需启用安全扫描，请：
+     1. 启动 skill-scanner-api 服务
+     2. 确认服务地址配置正确（当前: http://localhost:8000）
+     3. 重新执行安装操作
+     ```
+   - **不要阻止用户的操作**（如安装 Skill）
+   - **不要反复尝试连接**（避免延迟用户操作）
+
+**示例对话**：
+
+```
+用户: 帮我安装 caldav-calendar 这个 skill
+AI: 好的，让我先检查安全扫描服务...
+    [执行 health 检查]
+    
+    ⚠️ Skills 安全扫描服务当前不可用，已跳过安全检查。
+    
+    正在安装 caldav-calendar...
+    ✅ 安装完成
+    
+    💡 提示：如需启用安全扫描功能，请启动 skill-scanner-api 服务。
+```
+
+**为什么要跳过而不是阻止**：
+- 安全扫描是辅助功能，不应阻碍正常使用
+- 用户可能在离线环境或未配置扫描服务的环境中工作
+- 避免因服务问题导致所有 Skill 操作失败
+
 ### 1. VirusTotal 扫描结果优先提示 ⚠️
 
 **如果扫描结果中包含 VirusTotal 的扫描数据，必须优先、重点展示此结果，即使未检测到病毒。**
@@ -249,7 +298,7 @@ AI: 好的，让我先扫描一下这个 skill 的安全性...
 #### 示例 2：详细检查 PDF Skill
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} clawhub https://clawhub.ai/steipete/nano-pdf --detailed
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 clawhub https://clawhub.ai/steipete/nano-pdf --detailed
 ```
 
 **用户对话**：
@@ -272,7 +321,7 @@ AI: 好的，我会进行详细扫描...
 #### 示例 3：深度扫描可疑 Skill
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} clawhub https://clawhub.ai/username/suspicious-skill --detailed --behavioral --policy strict
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 clawhub https://clawhub.ai/username/suspicious-skill --detailed --behavioral --policy strict
 ```
 
 **用户对话**：
@@ -295,7 +344,7 @@ AI: 明白，我会使用严格模式进行深度扫描...
 #### 示例 4：包含 VirusTotal 扫描结果
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} clawhub https://clawhub.ai/username/project --detailed
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 clawhub https://clawhub.ai/username/project --detailed
 ```
 
 **用户对话（未检测到威胁）**：
@@ -408,25 +457,25 @@ https://clawhub.ai/<username>/<project>
 ### 基础扫描（推荐，速度快）
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径>
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 scan <skill路径>
 ```
 
 ### 详细模式（显示所有发现）
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径> --detailed
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 scan <skill路径> --detailed
 ```
 
 ### 深度扫描（加入行为分析）
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径> --detailed --behavioral
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 scan <skill路径> --detailed --behavioral
 ```
 
 ### 最强扫描（加入 LLM 语义分析）
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} scan <skill路径> --detailed --behavioral --llm
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 scan <skill路径> --detailed --behavioral --llm
 ```
 
 ---
@@ -438,31 +487,31 @@ https://clawhub.ai/<username>/<project>
 ### 扫描指定目录下的所有 Skills
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch <目录路径>
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 batch <目录路径>
 ```
 
 ### 递归扫描（含子目录）
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch <目录路径> --recursive
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 batch <目录路径> --recursive
 ```
 
 ### 批量扫描并输出 JSON 报告
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch <目录路径> --detailed --json /tmp/scan-report.json
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 batch <目录路径> --detailed --json /tmp/scan-report.json
 ```
 
 ### 常用目录示例
 
 扫描 OpenClaw 默认 skills 目录：
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch ~/.openclaw/skills
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 batch ~/.openclaw/skills
 ```
 
 扫描 workspace skills：
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} batch ~/.openclaw/workspace/skills --recursive
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 batch ~/.openclaw/workspace/skills --recursive
 ```
 
 ---
@@ -472,7 +521,7 @@ https://clawhub.ai/<username>/<project>
 检查 API 服务是否运行：
 
 ```bash
-{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url {apiUrl} health
+{baseDir}/.venv/bin/python {baseDir}/scan.py --api-url http://localhost:8000 health
 ```
 
 ---
@@ -533,7 +582,7 @@ https://clawhub.ai/<username>/<project>
 
 | 参数 | 说明 |
 |------|------|
-| `--api-url <url>` | API 服务地址（默认: http://localhost:8000） |
+| `--api-url <url>` | API 服务地址 |
 | `--detailed` | 显示每条 finding 的完整详情 |
 | `--behavioral` | 启用 AST 数据流分析（更准确，稍慢） |
 | `--llm` | 启用 LLM 语义分析（最准确，需 API 支持） |
@@ -561,7 +610,8 @@ https://clawhub.ai/<username>/<project>
 - VirusTotal 扫描需要 API 服务配置 VirusTotal API 密钥，否则不会包含 VirusTotal 数据。
 - VirusTotal 有 API 调用频率限制（免费版：4 次/分钟，付费版更高）。
 - 退出码 `0` 表示安全，`1` 表示存在问题（便于 CI/CD 集成）。
-- `{apiUrl}` 占位符会自动替换为插件配置中的 API URL。
+- `{baseDir}` 占位符会自动替换为 Skill 的安装目录。
+- 如果你配置了非默认的 API URL（如 `http://10.110.3.133`），请在命令中使用 `--api-url` 参数指定你的 URL。
 
 ### VirusTotal 特别说明