@pwddd/skills-scanner 1.0.0-beta.1

package/README.md

@@ -0,0 +1,255 @@
+# Skills Scanner Plugin
+
+OpenClaw Skills 安全扫描插件，用于检测 Skills 中的潜在安全威胁。
+
+## 功能特性
+
+- 🔍 **自动扫描**: 监听 Skills 目录，自动扫描新安装的 Skill
+- 🛡️ **安装前拦截**: 使用 before_install hook 在安装前强制拦截不安全的 Skills
+- 🌐 **ClawHub 扫描**: 直接扫描 ClawHub 上的 Skill，无需手动下载
+- 📊 **定时周报**: 每周一自动生成安全扫描报告
+- 🛡️ **多种策略**: 支持 strict/balanced/permissive 三种扫描策略
+- 🤖 **LLM 分析**: 可选的 LLM 语义分析
+- 🔒 **自动隔离**: 检测到不安全的 Skill 自动隔离或删除
+
+## 安装
+
+```bash
+# 从本地安装（开发）
+openclaw plugins install ./skills-scanner
+
+# 从 npm 安装（发布后）
+openclaw plugins install @pwddd/skills-scanner
+```
+
+## 配置
+
+在 `~/.openclaw/openclaw.json` 或工作区配置中添加：
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "skills-scanner": {
+        "enabled": true,
+        "config": {
+          "apiUrl": "https://110.vemic.com/skills-scanner",
+          "scanDirs": ["~/.openclaw/skills", "~/.openclaw/workspace/skills"],
+          "behavioral": false,
+          "useLLM": false,
+          "policy": "balanced",
+          "preInstallScan": "on",
+          "onUnsafe": "warn",
+          "enableBeforeInstallHook": true
+        }
+      }
+    }
+  }
+}
+```
+
+### 配置说明
+
+- `apiUrl`: 扫描 API 服务地址
+- `scanDirs`: 要监控的 Skills 目录列表
+- `behavioral`: 是否启用行为分析（深度扫描，较慢）
+- `useLLM`: 是否使用 LLM 进行语义分析
+- `policy`: 扫描策略
+  - `strict`: 严格模式，发现任何可疑行为都标记为不安全
+  - `balanced`: 平衡模式（推荐）
+  - `permissive`: 宽松模式，只标记明确的威胁
+- `preInstallScan`: 是否启用文件监控（安装后扫描）
+  - `on`: 启用
+  - `off`: 禁用
+- `onUnsafe`: 发现不安全 Skill 的处理方式
+  - `warn`: 仅警告，不处理（推荐）
+  - `quarantine`: 移入隔离目录
+  - `delete`: 直接删除
+- `enableBeforeInstallHook`: 是否启用 before_install hook（安装前拦截）
+  - `true`: 启用（强烈推荐）
+  - `false`: 禁用
+- `scanTimeoutMs`: 扫描超时时间（毫秒），默认 180000 (3分钟)
+- `reportDir`: 自定义报告目录
+- `quarantineDir`: 自定义隔离目录
+
+### 高级功能
+
+#### 配置热重载
+
+插件支持配置热重载，修改配置后无需重启 Gateway:
+
+```bash
+# 修改配置文件
+vim ~/.openclaw/config.json
+
+# 重载配置
+openclaw config reload
+```
+
+配置变更会自动:
+- 更新 API URL
+- 重启文件监控器（如果扫描目录变更）
+- 应用新的扫描策略
+
+#### 调试模式
+
+启用调试模式可以查看详细的运行日志:
+
+```bash
+# 启用调试模式
+export SKILLS_SCANNER_DEBUG=1
+openclaw gateway start
+
+# 或者一次性启用
+SKILLS_SCANNER_DEBUG=1 openclaw gateway start
+```
+
+调试模式会输出:
+- 完整的配置信息
+- 详细的扫描过程
+- API 请求和响应
+- 文件监控事件
+
+#### 健康检查端点
+
+插件提供 HTTP 健康检查端点:
+
+```bash
+# 通过 HTTP 访问
+curl http://localhost:3000/health/skills-scanner
+
+# 返回示例
+{
+  "status": "healthy",
+  "plugin": {
+    "version": "1.0.0",
+    "id": "skills-scanner",
+    "name": "Skills Scanner"
+  },
+  "api": {
+    "url": "https://110.vemic.com/skills-scanner",
+    "status": "available"
+  },
+  "watcher": {
+    "enabled": true,
+    "running": true,
+    "directories": 2
+  },
+  "metrics": {
+    "totalScans": 42,
+    "successRate": "95.24%",
+    "averageDurationMs": 1234
+  }
+}
+```
+
+## 使用方法
+
+### 聊天命令
+
+```
+/skills-scanner scan <路径> [选项]    # 扫描 Skill
+/skills-scanner scan clawhub <URL> [选项]  # 扫描 ClawHub Skill
+/skills-scanner health                # 健康检查
+/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 scan clawhub https://clawhub.ai/username/project
+/skills-scanner scan clawhub https://clawhub.ai/Asleep123/caldav-calendar --detailed
+/skills-scanner health
+```
+
+### CLI 命令
+
+```bash
+# 扫描单个 Skill
+openclaw skills-scanner scan <path> [--detailed] [--behavioral]
+
+# 扫描 ClawHub Skill
+openclaw skills-scanner clawhub <url> [--detailed] [--behavioral]
+
+# 批量扫描目录
+openclaw skills-scanner batch <directory> [--recursive] [--detailed]
+
+# 生成日报
+openclaw skills-scanner report
+
+# 检查 API 服务健康状态
+openclaw skills-scanner health
+```
+
+## 工作流程
+
+1. **插件启动**: 自动初始化并连接 API 服务
+2. **文件监控**: 监听配置的 Skills 目录
+3. **自动扫描**: 检测到新 Skill 时自动触发扫描
+4. **结果处理**: 根据配置隔离/删除/警告不安全的 Skill
+5. **定时周报**: 每周一 12:05 自动生成安全报告
+
+## 故障排除
+
+### API 服务连接失败
+
+1. 确保 API 服务地址配置正确
+2. 运行健康检查：`/skills-scanner health`
+3. 检查网络连接
+
+### 定时任务未注册
+
+定时任务会在插件启动时自动注册。如果需要手动注册：
+
+```bash
+# 手动注册定时任务
+/skills-scanner cron setup
+
+# 或使用 CLI
+openclaw cron add \
+  --name "skills-weekly-report" \
+  --cron "5 12 * * 1" \
+  --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/                      # 源代码
+│   ├── api-client.ts        # HTTP API 客户端
+│   ├── config.ts            # 配置管理
+│   ├── scanner.ts           # 扫描逻辑
+│   ├── watcher.ts           # 文件监控
+│   ├── cron.ts              # 定时任务
+│   ├── commands.ts          # 命令处理
+│   └── types.ts             # 类型定义
+└── skills/
+    └── skills-scanner/
+        └── SKILL.md         # Skill 文档
+```
+
+## 许可证
+
+MIT