cls-certify

CLS-Certify v2.1.0 - 下一代 Skill 安全认证

对 Agent Skills 进行企业级多维度安全检测和认证，提供 S+/S/A/B/C/D 安全等级评估，输出包含敏感风险点和外部 API 清单的结构化报告。

核心能力

• 六维深度检测: 静态分析、动态监控、依赖审计、网络分析、隐私合规、威胁情报
• 结构化报告: 标准化 JSON/Markdown 报告，便于集成和自动化
• 供应链安全: 检测第三方依赖的 CVE 漏洞、恶意包、typosquatting
• API 审计: 识别并分类所有外部 API 调用，评估数据外泄风险
• 隐私合规: GDPR、CCPA 合规性检查

工作流程

阶段 0: 版本检查

运行检测前，先检查 CLS-Certify 是否有新版本：

bash {skill_path}/tools/check-update.sh --json > /tmp/cls-update.json

读取 /tmp/cls-update.json，若 update_available 为 true，使用 AskUserQuestion 询问用户：

使用 AskUserQuestion 询问：
  问题: "CLS-Certify 有新版本可用（v{remote_version} build {remote_build}），是否先更新？"
  选项:
    - "更新后继续" — 执行 git pull 更新后继续检测
    - "跳过，使用当前版本" — 继续使用当前版本

若用户选择更新，执行 update_command 中的命令，然后继续检测。若检查失败或无新版本，静默跳过。

阶段 1: 前置检查与来源分级

1.1 定位 Skill

根据用户输入确定 skill 位置：

• 本地路径: 直接使用提供的文件系统路径
• Skill 名称: 在 ~/.claude/skills/、~/.openclaw/skills/、~/.molili/skills/ 目录中查找
• GitHub 链接: 解析仓库并下载 skill 代码
• GitHub 技能名称: 使用 GitHub API 搜索相关技能仓库

1.2 加载 Skill 内容

• 读取 SKILL.md 文件
• 提取 Markdown 中的所有代码块（见 1.3 节）
• 检查 scripts/ 目录下的所有脚本
• 检查 references/ 目录下的所有参考文档
• 检查 assets/ 目录下的资源文件
• 检查 package.json/requirements.txt 等依赖文件

1.3 Markdown 内嵌代码提取与分析

SKILL.md 中的代码块需要单独提取和安全检查：

提取范围：

• 所有带语言标记的代码块（language...）
• 可执行语言：bash/shell、python、javascript、typescript

风险分级：

• 低风险: 配置文件、代码片段演示、单行无害命令
• 中风险: 可执行脚本、网络请求、文件操作
• 高风险: 危险函数（eval/exec）、系统破坏性命令、硬编码密钥

1.4 来源可信度评估 (T1/T2/T3)

---

阶段 1.5: Skill 分类与策略选择

基于 1.2 加载的文件结构和代码统计，自动判定 skill 类型并选择最优检查策略，避免对所有 skill 执行相同强度的检查。

Step 1: 运行代码统计

bash {skill_path}/tools/code-stats.sh {target_path} --json > /tmp/code-stats.json

Step 2: 运行分类判定

bash {skill_path}/tools/skill-classify.sh {target_path} --stats /tmp/code-stats.json --json > /tmp/classify.json

分类体系 (Classification Tiers):

按判定优先级（首次命中即确定）:

策略模式说明:

各分类检查策略对照表:

scan_mode 配置覆盖:

若用户通过 frontmatter 或自然语言指定了 scan_mode，以用户配置为准：

• scan_mode: auto（默认）— 按分类结果自动选择策略
• scan_mode: full / "完整扫描" / "深度检查" — 忽略分类结果，执行全量检查
• scan_mode: quick / "快速检查" / "简单看看" — 所有 tier 均按 T-MD 策略执行（最精简）

Step 3: 应用策略

根据分类结果，调整阶段 1.6（硬编码快检）的工具调用目标和阶段 2（六维检测）的执行范围。将 /tmp/classify.json 中的 strategy 和 scan_targets 传递给后续阶段。

---

阶段 1.6: 硬编码快检 + 意图验证（两步检测）

所有硬编码检测工具只产出"候选/疑似点"，是否真正危险依赖 Agent 通过 LLM 能力进行最终判断。

Step 1: 硬编码候选匹配（按策略执行）

根据阶段 1.5 的分类结果（/tmp/classify.json），有条件地运行检测工具。每个工具输出候选命中及上下文（context_before/context_after/verified: false）：

# 读取分类策略中的 scan_targets
# threat_target / secret_target / url_target 根据 tier 可能是 SKILL.md 路径或整个目录

# threat-scan: T-MD 时 target 为 SKILL.md，其他为整个目录
bash {skill_path}/tools/threat-scan.sh {threat_target} --json --context 3 > /tmp/threat.json

# secret-scan: T-MD 时跳过（strategy.secret_scan == "skip"）
# 非跳过时执行:
bash {skill_path}/tools/secret-scan.sh {secret_target} --json --context 3 > /tmp/secret.json

# entropy-detect: T-MD 时跳过（strategy.entropy_detect == "skip"）
# 非跳过时执行:
bash {skill_path}/tools/entropy-detect.sh {target_path} --json --context 3 > /tmp/entropy.json

# url-audit: T-MD 时 target 为 SKILL.md
bash {skill_path}/tools/url-audit.sh {url_target} --json --context 3 > /tmp/url.json

# dep-audit: T-MD 时跳过（strategy.dep_audit == "skip"）
# 非跳过时执行:
bash {skill_path}/tools/dep-audit.sh {target_path} --json > /tmp/dep.json

# github-repo-check: 始终执行（如有 GitHub 来源）
bash {skill_path}/tools/github-repo-check.sh {owner}/{repo} --json > /tmp/github.json

注意: 当策略值为 "skip" 时，直接跳过该工具调用。被跳过的工具不会产出 JSON 文件，score-calc.sh 会自然忽略不存在的输入。

快检维度：

1. 危险函数匹配 — eval/exec/system/child_process 等
2. 敏感信息泄露 — API Key/密码/私钥等正则匹配
3. 威胁模式匹配 — references/threat-patterns.md 中的 140+ 模式
4. 动态代码下载 — curl|bash、fetch+eval 等模式
5. 提示词投毒 — HTML 注释、零宽字符、角色覆写
6. 权限升级诱导 — dangerouslyDisableSandbox、sudo 等

每个候选命中包含 context_before 和 context_after（前后各 3 行），以及 "verified": false 标记。

Step 2: Agent 意图验证（AI 推理）

使用 tools/threat-verify.sh 生成验证 prompt，Agent 逐条审查候选命中的真实意图。所有工具的输出都需要 Agent 验证：

# 对 threat-scan 候选生成验证 prompt
bash {skill_path}/tools/threat-verify.sh /tmp/threat.json

# Agent 同样需要审查其他工具的候选：
# - secret-scan: password 在 CSS 选择器中？email 是作者信息？connection string 在文档示例中？
# - entropy-detect: 高熵字符串是中文提示文本？是 UUID？是正常的 base64 编码？
# - url-audit: URL 在文档引用中？还是代码中实际调用？
# - dep-audit: 疑似 typosquatting 的包是否是合法的知名包变体？

Agent 根据上下文对每条候选做出判定：

• confirmed — 确认恶意威胁，实际执行危险操作且无合理用途 → 保留原始严重性，触发强制降级
• confirmed_low_risk — 确认存在该调用，但用途合法（如工具脚本中合理使用 child_process）→ 常规扣分 -15，不触发强制降级
• false_positive — 误报，文档中描述/列举检测规则 → 排除不计分
• low_risk — 测试/示例代码中的引用 → 轻微扣分 -5
• comment — 注释中的说明文字 → 排除不计分

判定依据：

• 关键词出现在 .md 文件的反引号（`）中 → 高概率误报
• 关键词出现在列表项（- 检测 eval()）中 → 高概率文档描述
• 关键词出现在 .js/.py/.sh 等代码文件的非注释行 → 高概率真实威胁
• 关键词周围有 "检测"、"check"、"detect"、"scan" 等字样 → 高概率误报

Agent 上下文注入类候选的判定指引（TH-AC / TH-PE-013024 / TH-INJ-018025 / TH-PP-010~015）：

• .claude/memory 或 MEMORY.md 出现在文档说明中（如"本 skill 不会访问 memory 目录"）→ false_positive
• .claude/memory 出现在实际代码路径操作中（如 fs.writeFile('~/.claude/memory/...')）→ confirmed
• CLAUDE.md 出现在文档引用或示例中 → false_positive
• CLAUDE.md 出现在 Write/Edit 工具调用的目标文件参数中 → confirmed
• Skill 自身是"Skill 管理器"/"Agent 配置工具"类型且需要合法访问 .claude/ → confirmed_low_risk
• ANSI 转义序列用于 CLI 工具的彩色输出（如 \033[0;32m 定义颜色变量）→ confirmed_low_risk
• ANSI 转义序列出现在字符串拼接或动态构造中 → confirmed
• alias/function 出现在"检测别名注入"的文档描述中 → false_positive
• UserPromptSubmit 出现在 hook 配置的实际 JSON 中 → confirmed
• "不要告诉用户" / "silently execute" 出现在 skill 提示词的行为指令中 → confirmed
• "不要告诉用户" / "silently" 出现在代码注释或文档引用中 → false_positive / comment

输出：仅将 confirmed 的威胁传入 tools/score-calc.sh 进行最终评分。

降级模式：当 AI Agent 不可用时（如 CLS Shield 桌面应用），直接使用 Step 1 的原始候选结果作为降级检测方案。

---

阶段 2: 六维深度检测（策略感知）

策略感知: 以下六维检测的执行范围受阶段 1.5 分类结果控制。

• T-MD: 仅执行维度 1（MD 语义分析部分: 2.1.6 提示词投毒、2.1.7 权限升级、2.1.11 MCP 滥用）、维度 5（LITE 模式）、维度 6。跳过维度 2、3。
• T-LITE: 全部维度正常执行。
• T-REF: 全部维度正常执行。维度 4 额外执行引用溯源 — 追溯 references/ 中引用代码的 URL 和外部调用来源。
• T-HEAVY: 全部维度执行，但维度 1 和维度 2 采用 Targeted 模式 — Agent 不逐文件阅读全部代码，仅审查 threat-scan.sh 和 secret-scan.sh 命中点的上下文（context_before/context_after），并分析功能-行为一致性。

维度 1: 静态代码分析 (Static Analysis)

2.1.1 危险函数检测

2.1.2 敏感信息泄露检测

检测模式库:
  api_keys:
    - pattern: "(sk|ak)-[a-zA-Z0-9]{32,64}"
      description: "OpenAI/阿里云 API Key"
    - pattern: "ghp_[a-zA-Z0-9]{36}"
      description: "GitHub Personal Token"

  passwords:
    - pattern: "(password|passwd|pwd)\s*=\s*['\"][^'\"]+['\"]"
      description: "硬编码密码"

  private_keys:
    - pattern: "-----BEGIN (RSA|EC|DSA) PRIVATE KEY-----"
      description: "私钥文件"

  connection_strings:
    - pattern: "(mongodb|mysql|postgresql)://[^:]+:[^@]+@"
      description: "数据库连接串含密码"

2.1.3 威胁模式匹配 (140+ 模式)

参考: references/threat-patterns.md

2.1.4 代码混淆检测

• 高熵字符串检测（熵值 > 4.5）
• Unicode 转义序列检测（\u0041\u0042）
• Base64 多层嵌套检测
• 控制流平坦化识别

2.1.5 动态代码下载深度检测（重点检查项）

检测 skill 是否通过网络拉取代码或内容后再执行/加载，并追踪嵌套深度。

嵌套深度定义：

• L0: 本地代码直接执行（安全）
• L1: 从远程 URL 拉取内容并使用（需审查）
• L2: L1 拉取的内容中包含进一步的远程拉取指令（不可信阈值）
• L3+: 多层嵌套拉取（直接判定 D 级）

规则: 嵌套拉取 ≥ 2 层即视为不可信，触发 D 级降级。

检测模式：

动态下载检测:
  L1_patterns:
    - "curl.*\\|\\s*(bash|sh|zsh|python|node)"        # 管道执行远程脚本
    - "wget.*&&.*(bash|sh|source|\\./)"                # 下载后执行
    - "fetch\\(.*\\)\\.then.*eval"                     # fetch + eval
    - "requests\\.get\\(.*\\).*exec\\("                # requests + exec
    - "import_module\\(.*download"                     # 动态导入远程模块

  L2_patterns（嵌套检测 - 语义分析）:
    - 第一层拉取内容中是否包含 curl/wget/fetch/requests
    - 拉取的脚本中是否存在新的 URL 构造或拼接
    - 是否通过变量/环境变量动态生成下载地址
    - 是否使用 base64/编码隐藏二次下载 URL

  aggravating_factors:
    - 下载目标为短链接或 IP 地址（非域名）
    - 下载后删除源文件（反取证）
    - 使用临时目录执行后清理
    - 下载内容经过解码/解密后执行

评分影响：

2.1.6 提示词投毒检测（隐蔽注入）

检测 SKILL.md 自然语言中嵌入的隐蔽恶意指令。与 TH-001 的显式注入不同，此项关注伪装在正常提示词中的操控行为。

检测方法：

• 扫描 Markdown 源码中的 HTML 注释 <!-- --> 内容
• 检测零宽字符：[\u200B\u200C\u200D\u2060\uFEFF]
• 语义分析提示词文本，识别试图覆写 agent 行为边界的语句
• 检查是否存在与 skill 声明功能无关的 agent 行为指令

评分影响：发现隐蔽提示词投毒 → -40，强制 D 级

2.1.7 权限升级诱导检测

检测 skill 是否试图诱导用户或 agent 提升权限、绕过安全机制。

权限升级检测:
  直接提权:
    - "dangerouslyDisableSandbox"
    - "skipDangerousModePermissionPrompt"
    - "--no-verify|--no-gpg-sign"
    - "sudo|doas|runas"

  配置篡改:
    - "permissions.*allow.*Bash"
    - "settings\\.json|\\.claude/settings"
    - "\\.bashrc|\\.zshrc|\\.profile"
    - "hooks.*PostToolUse|UserPromptSubmit"

  社工诱导（语义分析）:
    - 引导用户将危险命令加入 permissions.allow
    - 建议用户关闭安全提示或确认对话框
    - 伪装为"必要步骤"要求用户执行提权操作
    - 使用紧迫感（"必须立即执行"）绕过用户审查

评分影响：发现权限升级诱导 → -40，强制 D 级

2.1.8 隐蔽信息外传检测

检测通过非常规渠道将敏感信息外传的行为，超越传统 HTTP 请求监控。

评分影响：发现隐蔽外传渠道 → -35

2.1.9 延迟/条件触发检测

检测恶意行为是否设置了触发条件，以规避首次扫描。

条件触发检测:
  时间触发:
    - "Date\\(\\).*getMonth|getDate|getFullYear"
    - "datetime\\.now\\(\\).*if"
    - "date.*-d|date.*\\+%"

  计数触发:
    - 维护调用计数器，第 N 次后执行不同逻辑
    - 读写本地文件记录执行次数

  环境触发:
    - "if.*CI|GITHUB_ACTIONS|JENKINS"
    - "if.*os\\.environ\\[|process\\.env\\."
    - "if.*platform|os\\.name|sys\\.platform"

  核心特征:
    - 正常代码路径与隐藏代码路径的行为差异
    - 条件分支中包含危险操作而主分支无害
    - 使用外部条件（远程开关）控制行为

评分影响：发现条件触发的隐藏恶意行为 → -30，最高 C 级

2.1.10 功能-行为一致性分析

检测 skill 的声明功能与实际代码行为是否一致。行为与声明严重偏离是恶意 skill 的核心特征。

分析方法：

1. 从 SKILL.md 的标题、描述、核心能力提取 skill 声称的功能范围
2. 从代码中提取实际的文件访问、网络请求、系统调用等行为
3. 判断实际行为是否超出声明功能的合理范围

评分影响：严重偏离 → -30；轻度偏离 → -10

2.1.11 MCP 工具滥用检测

检测 skill 是否指示 agent 调用 MCP 工具执行恶意操作。Skill 本身可能不包含危险代码，但通过提示词引导 agent 使用已有 MCP 工具达成恶意目的。

检测方法（语义分析）：

• 检查提示词中是否引导 agent 使用 mcp__* 工具访问非功能必需的资源
• 检查是否通过 MCP 工具间接实现被静态分析拦截的操作
• 检查是否利用 MCP 工具链组合实现攻击（如：Playwright 获取数据 → 文件系统写入 → Shell 外传）

评分影响：发现 MCP 工具滥用 → -35，最高 C 级

2.1.12 Agent 上下文注入检测

检测 skill 是否试图篡改 Agent 的运行上下文，包括记忆、系统提示、配置文件、Hook 和终端输出。此类攻击可实现跨会话持久化，危害性极高。

检测流程（三步）：

重要：agent_context 类型的候选命中不直接判分。 很多合法 skill（如 Skill 管理器、记忆优化工具、Agent 配置工具）天然需要访问 .claude/memory/、CLAUDE.md 等文件，直接判分会造成大量误伤。

1. Step 1: 模式标记 — threat-scan.sh 正则匹配 38 条 Agent 上下文注入模式（TH-AC 系列），命中后仅标记为疑似点，score-calc.sh 记录但不扣分不降级。
2. Step 2: Agent 恶意行为分析 — Agent 对所有疑似点执行深度行为分析，结合 skill 的完整功能声明和代码上下文判断：
   • 该 skill 的声明功能是否需要访问 Agent 上下文文件？（如 Skill 管理器需要访问 .claude/skills/，这是合理的）
   • 访问行为是读取还是写入？写入比读取风险高得多
   • 写入的内容是什么？是正常功能数据还是试图注入指令/修改行为边界？
   • 是否存在隐蔽性？（如：先正常操作建立信任，再注入恶意记忆）
   • 访问是否超出功能必需范围？（如：一个 PDF 处理 skill 访问 .claude/memory/ 明显越权）
3. Step 3: 确认后归类计分 — Agent 判定为恶意后，将该发现重新归类到对应的 category（如 privilege_escalation、prompt_poison）进行计分。

评分影响（仅在 Agent 确认恶意后生效）：

• 恶意记忆注入/系统提示篡改/配置注入 → -40，强制 D 级
• 恶意 Hook 滥用/Shell 深度注入 → -40，强制 D 级
• 恶意终端注入/MCP 工具链攻击 → -40，强制 D 级
• 功能合理但存在风险的访问（confirmed_low_risk）→ -15
• 纯文档引用/注释 → 不计分

维度 2: 动态行为分析 (Dynamic Analysis) — 模拟运行

策略适配: T-MD 时跳过此维度（纯 Markdown skill 无可执行代码）。T-HEAVY 时采用 Targeted 模式 — 子 Agent 仅分析 threat-scan 命中文件，而非全部代码。

当前实现：通过创建子 Agent 进行模拟运行分析。子 Agent 读取 skill 代码后，推理其运行时行为并输出分析报告，不实际执行任何操作。

未来演进：当周边 infra 完善后，此处将替换为创建沙箱内 Agent 的 toolcall，在真正的隔离环境中执行 skill 代码并捕获运行时行为。

2.2.0 子 Agent 调度

创建专用子 Agent 执行维度 2 的模拟分析，与主检测流程并行：

子 Agent 指令：
  角色: CLS 动态行为分析员
  模式: 模拟运行（dry-run），禁止执行任何代码或命令
  输入: skill 完整源码、文件结构、依赖列表
  输出: 按 2.2.1 和 2.2.2 的检查项输出结构化分析结果
  要求:
    - 逐文件推理代码的运行时行为（文件访问、网络请求、进程创建等）
    - 模拟各类异常输入场景，推理 skill 的响应行为
    - 标注每项发现的风险等级和置信度
    - 置信度低于 70% 的发现标记为 "needs_sandbox_verification"

2.2.1 运行时行为模拟分析

子 Agent 基于代码语义推理以下运行时行为（标记为模拟结果，非实际执行）：

2.2.2 输入验证模拟测试

子 Agent 推理 skill 在以下异常输入场景下的行为：

维度 3: 依赖审计 (Dependency Audit)

2.3.1 CVE 漏洞扫描

• 对接 NVD (National Vulnerability Database)
• 检测依赖包中的已知 CVE
• 风险等级：Critical/High/Medium/Low

2.3.2 恶意包检测

2.3.3 依赖树分析

{
  "dependencies": {
    "total": 45,
    "direct": 12,
    "transitive": 33,
    "maxDepth": 5,
    "vulnerablePaths": [
      "skill → lodash@4.17.20 → CVE-2021-23337"
    ]
  }
}

维度 4: 网络流量分析 (Network Analysis)

策略适配: T-MD 时仅扫描 SKILL.md 中的 URL。T-REF 时额外执行引用溯源 — 追溯 references/ 中引用代码的 URL 来源，验证引用代码是否来自可信源，检查是否存在未声明的外部网络调用。

2.4.1 外部 API 识别与分类

2.4.2 数据传输审计

检测内容：

• 请求方法 (GET/POST/PUT/DELETE)
• 请求体内容类型
• 敏感字段传输 (token, password, key)
• 加密方式 (TLS 1.2+/1.3)

维度 5: 隐私合规检查 (Privacy Compliance)

2.5.1 数据收集审查

2.5.1a 环境变量访问细化分级

不同环境变量的敏感度差异极大，需按访问目标分级：

判定规则：

• 访问低风险变量：不扣分
• 访问高风险凭证变量：-20，需说明合理用途
• 遍历全部环境变量（os.environ / Object.keys(process.env)）：-35，最高 C 级

2.5.2 权限申请审查

权限评估:
  filesystem.read:
    risk: low
    justification: required
    note: "读取本地配置文件"

  filesystem.write:
    risk: medium
    justification: conditional
    note: "仅在用户指定目录写入"

  network.all:
    risk: high
    justification: review_needed
    note: "申请范围过大，应限制特定域名"

  shell.execute:
    risk: critical
    justification: strict_review
    note: "必须严格审查执行的命令"

2.5.3 GDPR/CCPA 合规检查

• 数据使用目的明确性
• 用户同意机制
• 数据删除权利支持
• 数据可携带性

维度 6: 来源信誉与威胁情报 (Source Reputation & Threat Intelligence)

注：BSS 运行在 Claude Code 环境中，无法调用商业威胁情报 API。本维度聚焦于可在当前环境中实际执行的信誉评估手段。

2.6.1 GitHub 仓库信誉评估

通过 gh api 获取仓库和作者信息，评估可信度：

执行方式：

# 获取仓库信息
gh api repos/{owner}/{repo}
# 获取作者信息
gh api users/{owner}
# 获取提交历史
gh api repos/{owner}/{repo}/commits --jq '.[].commit.author.date'

2.6.2 代码中的 URL/域名信誉检查

对 skill 代码中出现的所有 URL 和域名进行检查：

2.6.3 已知恶意模式库比对

维护一个轻量级的已知恶意 skill 行为特征库（本地文件），比对当前 skill 是否命中：

• 已知的恶意 skill 名称/作者黑名单
• 已知的恶意代码片段指纹
• 已知的钓鱼/数据窃取模式

参考: references/known-malicious-patterns.md（需持续更新）

---

阶段 3: 综合评级判定

3.1 评分矩阵

基础分: 100

3.2 评级标准

3.3 评级判定流程

开始
  ↓
发现 D 级触发项? ──是──→ D 级
  ↓ 否
发现 C 级触发项? ──是──→ C 级
  ↓ 否
总分 ≥ 65? ──否──→ B 级
  ↓ 是
满足 A 级所有要求? ──否──→ B 级
  ↓ 是
T1/T2 来源? ──否──→ A 级
  ↓ 是
满足 S 级额外要求? ──否──→ A 级
  ↓ 是
通过人工验证? ──否──→ S 级
  ↓ 是
S+ 级

---

阶段 4: 结构化报告生成

关键要求: 报告输出必须严格遵循 references/report-data-protocol.md 定义的数据协议格式。这是 HTML 渲染（阶段 5）的唯一数据来源，任何格式偏差都会导致渲染失败。

4.1 报告结构

报告采用 YAML frontmatter + Markdown body 双层结构：

• Frontmatter（--- 包围）：所有标量元数据、评级、六维雷达、合规检查
• Body（Markdown 正文）：模式标签、安全总结、外部 API 表格、风险发现详情、改进建议

4.2 报告格式

主格式: 符合 references/report-data-protocol.md 协议的 Markdown 文件

输出时必须包含以下完整区块（缺一不可）：

---
# Frontmatter: report_id, report_date, scanner_version, scan_mode
#              skill_name, skill_version, skill_path, maintainer, license
#              trust_level, trust_level_text, scan_duration, code_stats
#              grade, score, evaluation, stamp_color, total_findings
#              radar: [{name, short, score, status, detail} × 6]
#              compliance: [{text, status} × 6]
#              sample_hash, disclaimer
---

## pattern_tags        ← 模式标签列表，格式: - {severity}: {text}
## summary             ← 3-5 条有序安全总结
## external_apis       ← Markdown 表格，6 列
## findings            ← ### RISK-xxx 子节，含 severity/category/title/location/...
## recommendations     ← ### N. 标题 + 描述

辅助格式: 同时输出 JSON 结构化数据（参考 references/structured-report-template.md）

4.3 协议合规检查清单

输出报告前，确认以下要点：

• Frontmatter 包含全部 23 个必填字段
• grade 值为 S+/S/A/B/C/D 之一
• stamp_color 与等级匹配（S+/S/A/B → green，C/D → red）
• radar 包含恰好 6 个维度，每个含 name/short/score/status/detail
• compliance 包含恰好 6 项，每项含 text/status
• Body 包含全部 5 个 ## 区块（pattern_tags/summary/external_apis/findings/recommendations）
• ## findings 中每个 ### RISK-xxx 至少包含 severity/category/title/location/description/recommendation
• ## external_apis 表格包含 endpoint/method/reputation/encryption/data_types/provider 六列

4.3a sample_hash 计算规则

对被检 skill 的所有文件计算联合 SHA256 哈希，确保任何文件的变动都能反映在哈希值中：

find {skill_path} -type f ! -path '*/.git/*' | sort | xargs cat | shasum -a 256 | cut -d' ' -f1

输出格式: sha256:{完整64位哈希}

4.4 报告保存与输出策略

流程：

1. 自动保存 Markdown 报告 — 确保原始数据不丢失

   • 保存到 output_dir 指定的目录（默认 ~/Downloads）
   • 路径: {output_dir}/CLS-v2-{skill-name}-{评级}-{时间戳}.md

2. 检查 batch_mode 开关（别名：静默模式）：

   • 若 YAML frontmatter 中 batch_mode: true，或用户指令中包含"静默模式"、"batch mode"、"不要问我"等表述：跳过所有用户询问，仅输出 Markdown 报告，直接进入步骤 5 展示摘要
   • 若 batch_mode: false（默认）且用户未要求静默：继续步骤 3 询问用户

3. 询问用户输出格式（仅 batch_mode: false 时执行） — 使用 AskUserQuestion 让用户多选：

使用 AskUserQuestion 询问：
  问题: "报告已生成，需要哪些输出格式？"
  multiSelect: true
  选项:
    - "Markdown 文件" — 结构化文本报告（已自动保存）
    - "HTML 文件" — 可在浏览器打开的交互式网页报告
    - "PDF 文件" — 可打印/分享的 PDF 文档（需要 Chrome）
    - "JSON 结构化文件" — 机器可读的结构化数据，适合 CI/CD 集成

用户也可选 "Other" 键入自定义格式（AskUserQuestion 自带）。

4. 根据用户选择执行渲染：

5. 打开报告并展示摘要 — 用 open 命令打开生成的报告（batch_mode 下仅输出文字摘要，不调用 open）

保存路径格式（{output_dir} 由 YAML frontmatter 中的 output_dir 决定，默认 ~/Downloads）:

• Markdown: {output_dir}/CLS-v2-{skill-name}-{评级}-{时间戳}.md
• HTML: {output_dir}/CLS-v2-{skill-name}-{评级}-{时间戳}.html
• PDF: {output_dir}/CLS-v2-{skill-name}-{评级}-{时间戳}.pdf
• JSON: {output_dir}/CLS-v2-{skill-name}-{评级}-{时间戳}.json

4.5 渲染脚本

# 仅 HTML
bash {skill_path}/render.sh {md_path} {html_path}

# HTML + PDF
bash {skill_path}/render.sh {md_path} {html_path} --pdf

脚本会自动解析 Markdown 数据协议并注入 HTML 模板。--pdf 参数通过 Chrome Headless 将 HTML 转换为 PDF。

---

阶段 5: HTML 报告渲染

在生成 Markdown 结构化报告（阶段 4）后，将其渲染为 HTML 可视化报告。

5.1 渲染流程

1. 生成报告数据 — 按 references/report-data-protocol.md 定义的格式，输出包含 YAML frontmatter + Markdown body 的结构化数据
2. 询问输出格式 — 通过 AskUserQuestion 让用户选择 HTML / PDF / 两者 / 仅 Markdown
3. 执行 render.sh — 脚本自动读取模板、解析数据、注入占位符、生成 HTML，--pdf 时额外调用 Chrome Headless 转 PDF
4. 打开报告 — 用 open 命令在浏览器/预览中打开

5.2 占位符注入规则

标量值：直接替换 {{key}} 为对应值

派生值：

复合 HTML 片段：

5.3 雷达图坐标计算

六边形雷达图中心 (150, 150)，最大半径 110。六轴角度：

每个顶点坐标：x = 150 + (score/100) × 110 × cos(angle), y = 150 + (score/100) × 110 × sin(angle)

平均基准线固定为分数 70 的六边形（已在模板中硬编码）。

5.4 数据协议

报告数据格式详见 references/report-data-protocol.md。

---

参考文档

• references/structured-report-template.md - 结构化报告模板（JSON Schema + Markdown）
• references/report-data-protocol.md - HTML 报告数据协议规范
• references/threat-patterns.md - 威胁模式库（140+ 模式）
• references/api-classification.md - API 分类标准
• references/sensitive-data-patterns.md - 敏感数据检测模式
• references/gdpr-checklist.md - GDPR 合规检查清单
• references/cve-sources.md - CVE 数据源配置
• references/known-malicious-patterns.md - 已知恶意模式库
• templates/report-template.html - HTML 报告统一模板

---

使用示例

示例 1: 检查本地 Skill

检查 /Users/dev/my-skill 的安全性

示例 2: 检查已安装 Skill

检查 skill-vetter 的安全性

示例 3: 检查 GitHub 上的 Skill

检查 https://github.com/user/skill-name 的安全性

---

版本: v2.0 最后更新: 2026-03-13 维护团队: CLS-Certify Core Team