@pwddd/skills-scanner 2.4.1 → 2026.3.10

package/README.md

@@ -1,431 +1,199 @@
-# openclaw-skills-scanner
-
-OpenClaw Plugin，通过 HTTP API 调用远程 [cisco-ai-skill-scanner](https://github.com/cisco-ai-defense/skill-scanner) 服务实现对 OpenClaw Skills 的安全扫描。
-
-## 架构说明
-
-本插件采用 **HTTP 客户端模式**：
-- **客户端**：本插件（TypeScript + Python HTTP 客户端）
-- **服务端**：独立运行的 `skill-scanner-api` 服务（需单独部署）
-- **通信方式**：通过 HTTP REST API 调用扫描服务
-
-### 为什么使用 HTTP 模式？
-
-1. **依赖隔离**：避免复杂的 Python 依赖安装问题（LiteLLM、代理配置等）
-2. **服务复用**：多个客户端可共享同一个扫描服务
-3. **灵活部署**：扫描服务可部署在专用服务器上，支持更强大的硬件配置
-4. **简化维护**：客户端只需 `requests` 库，无需安装完整的 `cisco-ai-skill-scanner`
-
-## 功能
-
-| 功能 | 实现方式 | 状态 |
-|---|---|---|
-| 启动时自动安装 Python 依赖（requests） | `registerService` | ✅ 全自动 |
-| `/skills-scanner` 统一命令入口 | `registerCommand` | ✅ 全自动 |
-| `openclaw skills-scan` CLI | `registerCli` | ✅ 全自动 |
-| 安装前扫描（新 Skill 出现时自动扫描） | `fs.watch` | ✅ 全自动 |
-| Gateway 启动时在日志里打印配置提示 | Plugin Hook `gateway:startup` | ✅ 全自动 |
-| 每日定期日报 | Cron Job | ✅ 智能自动注册 |
-
----
-
-## 前置要求
-
-### 1. 启动 skill-scanner-api 服务
-
-在服务器上安装并启动 API 服务：
-
-```bash
-# 安装 cisco-ai-skill-scanner
-pip install cisco-ai-skill-scanner
-
-# 启动 API 服务（默认端口 8000）
-skill-scanner-api
-
-# 或指定端口
-skill-scanner-api --port 8080
-
-# 开发模式（自动重载）
-skill-scanner-api --reload
-```
-
-验证服务是否正常：
-
-```bash
-curl http://localhost:8000/health
-```
-
-### 2. 安装本插件
-
-```bash
-# 从本地目录安装
-openclaw plugins install ./openclaw-skills-scanner
-
-# 或从 npm 安装
-openclaw plugins install @pwddd/skills-scanner
-
-# 重启 Gateway（Plugin 变更必须重启）
-openclaw gateway restart
-```
-
-重启后 Gateway 会自动：
-1. 创建 Python venv 并安装 `requests` 库
-2. 开始监听 Skills 目录（安装前扫描）
-3. **智能注册定时任务**（检测已有任务，防止重复）
-
----
-
-## 定时任务自动注册
-
-插件启动时会**自动智能注册**定时任务，特点：
-
-- ✅ **幂等操作**：多次启动不会创建重复任务
-- ✅ **智能检测**：自动发现已存在的同名任务
-- ✅ **自动更新**：配置变更时自动更新任务
-- ✅ **防止冲突**：即使手动创建过任务也能正确识别
-
-如果自动注册失败，可以使用 `/skills-scanner cron register` 命令手动注册。
-
----
-
-## 注册每日日报（已自动化）
-
-~~Plugin 无法自动注册 Cron Job（OpenClaw Plugin API 不提供此能力），需要手动执行一次：~~
-
-**更新**：从 v2.2.0 开始，插件会在启动时自动注册定时任务，无需手动操作！
-
-如果需要手动管理，使用以下命令：
-
-如果需要手动管理，使用以下命令：
-
-```bash
-# 使用聊天命令（推荐）
-/skills-scanner cron register    # 注册定时任务
-/skills-scanner cron unregister  # 删除定时任务
-/skills-scanner cron status      # 查看状态
-
-# 或使用 CLI 命令
-openclaw cron add \
-  --name "skills-daily-report" \
-  --cron "0 8 * * *" \
-  --tz "Asia/Shanghai" \
-  --session isolated \
-  --message "请执行 /skills-scanner scan --report 并把结果发送到此渠道" \
-  --announce
-```
-
-验证已注册：
-
-```bash
-openclaw cron list
-```
-
----
-
-## 聊天命令
-
-### 主命令
-
-```bash
-/skills-scanner [子命令] [参数]
-```
-
-### 子命令
-
-| 命令 | 说明 |
-|---|---|
-| `/skills-scanner scan <路径> [选项]` | 扫描 Skill（智能判断单个/批量） |
-| `/skills-scanner status` | 查看状态、API 服务、定时任务 |
-| `/skills-scanner config [操作]` | 配置管理（show/reset） |
-| `/skills-scanner cron [操作]` | 定时任务管理（register/unregister/status） |
-| `/skills-scanner help` | 显示帮助文档 |
-
-### 扫描选项
-
-| 选项 | 说明 |
-|---|---|
-| `--detailed` | 显示所有 findings 详情 |
-| `--behavioral` | 启用 AST 行为分析（更准确但较慢） |
-| `--recursive` | 递归扫描子目录 |
-| `--report` | 生成日报格式输出 |
-
-### 使用示例
-
-```bash
-# 扫描单个 Skill
-/skills-scanner scan ~/.openclaw/skills/my-skill
-
-# 批量扫描（递归）
-/skills-scanner scan ~/.openclaw/skills --recursive
-
-# 生成日报
-/skills-scanner scan ~/.openclaw/skills --report
-
-# 详细扫描 + 行为分析
-/skills-scanner scan ~/my-skill --detailed --behavioral
-
-# 查看状态
-/skills-scanner status
-
-# 配置管理
-/skills-scanner config show
-/skills-scanner config reset
-
-# 定时任务管理
-/skills-scanner cron status
-/skills-scanner cron register
-/skills-scanner cron unregister
-
-# 查看帮助
-/skills-scanner help
-```
-
----
-
-## CLI 命令
-
-### 可用命令
-
-```bash
-openclaw skills-scan <子命令> [参数]
-```
-
-### 子命令
-
-| 命令 | 说明 |
-|---|---|
-| `scan <路径>` | 扫描单个 Skill |
-| `batch <目录>` | 批量扫描目录 |
-| `report` | 生成完整日报 |
-| `health` | 检查 API 服务状态 |
-
-### 使用示例
-
-```bash
-# 扫描单个 Skill
-openclaw skills-scan scan ~/.openclaw/skills/my-skill
-
-# 批量扫描
-openclaw skills-scan batch ~/.openclaw/skills --recursive
-
-# 生成日报
-openclaw skills-scan report
-
-# 健康检查
-openclaw skills-scan health
-
-# 详细扫描
-openclaw skills-scan scan ~/my-skill --detailed --behavioral
-```
-
-**注意**：CLI 命令是 `skills-scan`（不是 `skills-scanner`）
-
----
-
-## 命令对比
-
-| 功能 | 聊天命令 | CLI 命令 |
-|---|---|---|
-| 扫描单个 Skill | `/skills-scanner scan <路径>` | `openclaw skills-scan scan <路径>` |
-| 批量扫描 | `/skills-scanner scan <目录> --recursive` | `openclaw skills-scan batch <目录> --recursive` |
-| 生成日报 | `/skills-scanner scan --report` | `openclaw skills-scan report` |
-| 查看状态 | `/skills-scanner status` | - |
-| 健康检查 | `/skills-scanner status`（包含） | `openclaw skills-scan health` |
-| 配置管理 | `/skills-scanner config` | - |
-| 定时任务 | `/skills-scanner cron` | - |
-
----
-
-## 定时任务说明
-
-插件会在启动时**自动智能注册**定时任务，无需手动操作：
-
-### 智能注册机制
-
-1. **检测已有任务**：启动时查询系统中是否已有同名任务
-2. **幂等操作**：如果任务已存在，保存 ID 并跳过创建
-3. **自动更新**：如果任务配置变更（时间、时区），自动删除旧任务并创建新任务
-4. **防止重复**：即使多次重启或重新安装，也不会创建重复任务
-
-### 默认配置
-
-- **任务名称**：`skills-daily-report`
-- **执行时间**：每天 08:00
-- **时区**：Asia/Shanghai
-- **执行内容**：发送 `/skills-scanner scan --report` 命令到指定渠道
-
-### 手动管理
-
-如果自动注册失败，可以手动操作：
-
-```bash
-# 查看所有定时任务
-openclaw cron list
-
-# 手动注册
-openclaw cron add \
-  --name "skills-daily-report" \
-  --cron "0 8 * * *" \
-  --tz "Asia/Shanghai" \
-  --session isolated \
-  --message "请执行 /skills-scanner scan --report 并把结果发送到此渠道" \
-  --announce
-
-# 删除定时任务
-openclaw cron remove <job-id>
-
-# 修改执行时间（先删除再创建）
-openclaw cron remove <job-id>
-openclaw cron add --name "skills-daily-report" --cron "0 9 * * *" ...
-```
-
-### 投递到特定渠道
-
-如果想将日报发送到特定渠道（如 Telegram）：
-
-```bash
-openclaw cron add \
-  --name "skills-daily-report" \
-  --cron "0 8 * * *" \
-  --tz "Asia/Shanghai" \
-  --session isolated \
-  --message "请执行 /skills-scanner scan --report 并把结果发送到此渠道" \
-  --announce \
-  --channel telegram \
-  --to "+8613312345678"
-```
-
----
-
-## 安装前扫描说明
-
-Plugin 启动后用 `fs.watch` 监听所有 Skills 目录。任何新 Skill 出现（无论通过 `clawhub install`、CLI 还是手动复制）都会触发扫描。
-
-扫描结果通过 `persistWatcherAlert` 写入 `~/.openclaw/skills-scanner/state.json`，运行 `/skills-scanner status` 查看并清空告警列表。
-
-> **为什么不直接发聊天消息？**
-> OpenClaw Plugin API 没有提供在后台任务里主动推送消息给用户的方法。`event.messages.push()` 只在 Hook handler 的同步上下文中有效，`registerCommand` 的 handler 需要用户主动触发。这是平台限制，不是实现缺陷。
-
-处置方式通过 `onUnsafe` 配置：
-
-| 值 | 行为 |
-|---|---|
-| `"quarantine"`（默认）| 移入 `~/.openclaw/skills-scanner/quarantine/` |
-| `"delete"` | 直接删除 |
-| `"warn"` | 仅写告警日志，保留文件 |
-
----
-
-## 配置
-
-```jsonc
-// ~/.openclaw/openclaw.json
-{
-  "plugins": {
-    "entries": {
-      "skills-scanner": {
-        "enabled": true,
-        "config": {
-          "apiUrl": "http://localhost:8000",    // API 服务地址
-          "scanDirs": ["~/.openclaw/skills"],   // 留空自动检测
-          "behavioral": false,                  // 行为分析（较慢）
-          "useLLM": false,                      // 启用 LLM 分析
-          "policy": "balanced",                 // strict | balanced | permissive
-          "preInstallScan": "on",               // fs.watch 安装前扫描
-          "onUnsafe": "quarantine"              // quarantine | delete | warn
-        }
-      }
-    }
-  }
-}
-```
-
-### 配置说明
-
-| 配置项 | 类型 | 默认值 | 说明 |
-|---|---|---|---|
-| `apiUrl` | string | `http://localhost:8000` | skill-scanner-api 服务地址 |
-| `scanDirs` | string[] | 自动检测 | 要扫描的 Skills 目录列表 |
-| `behavioral` | boolean | `false` | 启用行为分析（更准确但较慢） |
-| `useLLM` | boolean | `false` | 启用 LLM 分析（需 API 服务配置 LLM） |
-| `policy` | string | `balanced` | 扫描策略：`strict`（严格）/ `balanced`（平衡）/ `permissive`（宽松） |
-| `preInstallScan` | string | `on` | 是否启用 fs.watch 安装前扫描 |
-| `onUnsafe` | string | `quarantine` | 发现不安全 Skill 时的处置方式 |
-
----
-
-## HTTP API 端点说明
-
-本插件使用以下 API 端点：
-
-| 端点 | 方法 | 用途 |
-|---|---|---|
-| `/health` | GET | 健康检查 |
-| `/scan-upload` | POST | 上传 ZIP 文件扫描（单个 Skill） |
-| `/scan-batch` | POST | 批量异步扫描（服务器本地目录） |
-| `/scan-batch/{scan_id}` | GET | 查询批量扫描结果 |
-
-### 扫描方式
-
-1. **单个 Skill 扫描**：使用 `/scan-upload` 端点
-   - 客户端将 Skill 目录打包成 ZIP
-   - 上传到服务器
-   - 服务器解压并扫描
-   - 返回扫描结果
-
-2. **批量扫描（服务器本地）**：使用 `/scan-batch` 端点
-   - 适用于服务器本地目录
-   - 异步执行，返回 scan_id
-   - 轮询 `/scan-batch/{scan_id}` 获取结果
-
-3. **批量扫描（客户端上传）**：客户端循环调用 `/scan-upload`
-   - 适用于客户端本地多个 Skills
-   - 逐个打包上传扫描
-
----
-
-## 故障排查
-
-### 1. 连接失败
-
-```
-✗ 无法连接到 API 服务: http://localhost:8000
-```
-
-**解决方法**：
-- 确认 `skill-scanner-api` 服务正在运行
-- 检查配置中的 `apiUrl` 是否正确
-- 测试连接：`curl http://localhost:8000/health`
-
-### 2. 代理问题
-
-如果遇到代理相关错误，插件会自动清除代理环境变量。如果仍有问题，手动清除：
-
-```bash
-unset http_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY
-```
-
-### 3. Python 依赖问题
-
-```
-⏳ Python 依赖尚未就绪
-```
-
-**解决方法**：
-- 检查 `uv` 是否安装：`uv --version`
-- 手动安装依赖：
-  ```bash
-  cd ~/.openclaw/extensions/skills-scanner/skills/skills-scanner
-  uv venv .venv --python 3.10
-  uv pip install --python .venv/bin/python requests>=2.31.0
-  ```
-
----
-
-## 发布到 npm
-
-```bash
-# 已发布为 @pwddd/skills-scanner
-npm login
-npm publish --access public
-```
+# Skills Scanner Plugin
+
+OpenClaw Skills 安全扫描插件，用于检测 Skills 中的潜在安全威胁。
+
+## 功能特性
+
+- 🔍 **自动扫描**: 监听 Skills 目录，自动扫描新安装的 Skill
+- 📊 **定时日报**: 每天自动生成安全扫描报告
+- 🛡️ **多种策略**: 支持 strict/balanced/permissive 三种扫描策略
+- 🤖 **LLM 分析**: 可选的 LLM 语义分析
+- 🔒 **自动隔离**: 检测到不安全的 Skill 自动隔离或删除
+
+## 安装
+
+```bash
+# 从本地安装（开发）
+openclaw plugins install ./extensions/skills-scanner
+
+# 从 npm 安装（发布后）
+openclaw plugins install @openclaw/skills-scanner
+```
+
+## 配置
+
+在 `~/.openclaw/config.json` 或工作区配置中添加：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "skills-scanner": {
+        "enabled": true,
+        "config": {
+          "apiUrl": "http://localhost:8000",
+          "scanDirs": ["~/.openclaw/skills", "~/.openclaw/workspace/skills"],
+          "behavioral": false,
+          "useLLM": false,
+          "policy": "balanced",
+          "preInstallScan": "on",
+          "onUnsafe": "quarantine"
+        }
+      }
+    }
+  }
+}
+```
+
+### 配置说明
+
+- `apiUrl`: 扫描 API 服务地址（需要先启动 skill-scanner-api 服务）
+- `scanDirs`: 要监控的 Skills 目录列表
+- `behavioral`: 是否启用行为分析（深度扫描，较慢）
+- `useLLM`: 是否使用 LLM 进行语义分析
+- `policy`: 扫描策略
+  - `strict`: 严格模式，发现任何可疑行为都标记为不安全
+  - `balanced`: 平衡模式（推荐）
+  - `permissive`: 宽松模式，只标记明确的威胁
+- `preInstallScan`: 是否在安装时自动扫描
+  - `on`: 启用（推荐）
+  - `off`: 禁用
+- `onUnsafe`: 发现不安全 Skill 的处理方式
+  - `quarantine`: 移入隔离目录（推荐）
+  - `delete`: 直接删除
+  - `warn`: 仅警告，不处理
+
+## 使用方法
+
+### 聊天命令
+
+```
+/skills-scanner scan <路径> [选项]    # 扫描 Skill
+/skills-scanner status                # 查看状态
+/skills-scanner config [操作]         # 配置管理
+/skills-scanner cron [操作]           # 定时任务管理
+/skills-scanner help                  # 帮助信息
+```
+
+#### 扫描选项
+
+- `--detailed`: 显示详细的安全发现
+- `--behavioral`: 启用行为分析
+- `--recursive`: 递归扫描子目录
+- `--report`: 生成日报格式
+
+#### 示例
+
+```
+/skills-scanner scan ~/.openclaw/skills/my-skill
+/skills-scanner scan ~/.openclaw/skills --recursive
+/skills-scanner scan ~/.openclaw/skills --report
+/skills-scanner status
+```
+
+### CLI 命令
+
+```bash
+# 扫描单个 Skill
+openclaw skills-scan scan <path> [--detailed] [--behavioral]
+
+# 批量扫描目录
+openclaw skills-scan batch <directory> [--recursive] [--detailed]
+
+# 生成日报
+openclaw skills-scan report
+
+# 检查 API 服务健康状态
+openclaw skills-scan health
+```
+
+## 前置要求
+
+### 1. 安装 uv（Python 包管理器）
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 或使用 Homebrew
+brew install uv
+```
+
+### 2. 启动扫描 API 服务
+
+插件需要连接到 skill-scanner-api 服务进行实际的安全扫描。
+
+```bash
+# 启动服务（假设你已经有这个服务）
+skill-scanner-api
+```
+
+默认服务地址为 `http://localhost:8000`，可以在配置中修改。
+
+## 工作流程
+
+1. **插件启动**: 自动安装 Python 依赖（requests）
+2. **文件监控**: 监听配置的 Skills 目录
+3. **自动扫描**: 检测到新 Skill 时自动触发扫描
+4. **结果处理**: 根据配置隔离/删除/警告不安全的 Skill
+5. **定时日报**: 每天 08:00 生成安全报告
+
+## 故障排除
+
+### Python 依赖安装失败
+
+```bash
+# 手动安装依赖
+cd extensions/skills-scanner/skills/skills-scanner
+uv venv .venv --python 3.10
+uv pip install --python .venv/bin/python requests>=2.31.0
+```
+
+### API 服务连接失败
+
+1. 确保 skill-scanner-api 服务正在运行
+2. 检查配置中的 `apiUrl` 是否正确
+3. 运行健康检查：`openclaw skills-scan health`
+
+### 定时任务未注册
+
+```bash
+# 手动注册定时任务
+/skills-scanner cron register
+
+# 或使用 CLI
+openclaw cron add \
+  --name "skills-daily-report" \
+  --cron "0 8 * * *" \
+  --tz "Asia/Shanghai" \
+  --session isolated \
+  --message "请执行 /skills-scanner scan --report 并把结果发送到此渠道" \
+  --announce
+```
+
+## 开发
+
+### 目录结构
+
+```
+extensions/skills-scanner/
+├── package.json              # npm 包配置
+├── openclaw.plugin.json      # 插件元数据
+├── README.md                 # 文档
+├── index.ts                  # 插件入口
+├── src/                      # 源代码
+│   ├── config.ts            # 配置管理
+│   ├── scanner.ts           # 扫描逻辑
+│   ├── watcher.ts           # 文件监控
+│   ├── cron.ts              # 定时任务
+│   ├── commands.ts          # 命令处理
+│   └── types.ts             # 类型定义
+└── skills/
+    └── skills-scanner/
+        ├── scan.py          # Python 扫描脚本
+        └── .venv/           # Python 虚拟环境（自动创建）
+```
+
+## 许可证
+
+MIT