# 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 级：**

- 存在严重安全问题
- 强烈建议不要使用
- 如需使用，必须在完全隔离的环境中