alibabacloud-openclaw-skill-security-scan

安全扫描技能

说明：本文档中的 {{SELF}} 均指上方 YAML name 字段中声明的技能名称。它仅用作下方自我排除规则的占位符。

此技能会执行全面的安全审计：技能风险评估（云端情报、本地静态分析、云端深度分析）+ 配置安全审计。

⚠️ 只读脚本——强烈建议：此技能下的所有脚本（scripts/main.sh 等）均为只读资源。强烈建议不要修改、修补、重写这些脚本，也不要创建会改变其行为的包装脚本。这包括更改文件大小限制、超时时间、分块大小、上传阈值或任何其他可配置值等参数。如果扫描遇到限制（例如文件过大），请如实向用户报告限制——避免通过编辑脚本来绕过限制。

⚠️ 自我排除规则：必须始终排除 {{SELF}}，不得对其进行扫描。构建技能列表时，Agent 必须移除此技能，且绝不能将其路径传递给 main.sh。脚本内部也会跳过此名称，但 Agent 应在调用前完成排除，避免在任何扫描工作流中包含自身。

---

适用场景

场景	示例触发词
全面评估	security scan、security analysis、skill audit、OpenClaw health check、OpenClaw安全评估、安全扫描、安全分析、风险评估、安全体检
配置审计	config audit、security baseline check、OpenClaw security audit、server exposure check、配置审计、检查OpenClaw配置、安全基线
技能扫描	scan skill for risks、supply chain security、skill安全扫描、检查skill风险、skill是否安全
安装前检查	pre-install safety check、is this skill safe、deployment safe、安装前检查、这个skill安全吗、能不能装这个skill

快速开始

⚠️ 必备前提：调用 main.sh 前，Agent 必须完成以下两步：

1. 授予脚本执行权限（安装/更新后运行一次）：chmod +x ./scripts/*.sh
2. 解析并传递技能路径：main.sh 不会自动发现技能路径；如果未提供路径参数，就会报错退出。Agent 必须自行解析技能路径，排除 {{SELF}}，然后通过以下三种方法之一传递其余路径。

路径传递方法

main.sh 支持以下三种互斥的技能路径传递方法。Agent 应选择其中一种：

方法 1：--skill-mapping（推荐）

以 name:path 格式同时传递技能名称和路径；多个技能之间用空格分隔。

./scripts/main.sh --skill-mapping \
  "skill-name-1:/home/user/.openclaw/skills/skill-name-1" \
  "skill-name-2:/home/user/.openclaw/skills/skill-name-2"

• 格式：<skill-name>:<absolute-path>，以冒号分隔，先写名称，再写路径
• 名称：技能的注册名称
• 路径：技能安装目录的绝对路径，该目录必须包含 SKILL.md 文件
• 验证：脚本会自动检查路径是否存在以及是否包含 SKILL.md；无效条目会被跳过并显示警告

方法 2：--skill-paths

仅传递路径。脚本会自动从每个 SKILL.md YAML front matter 中的 name: 字段提取技能名称；如果提取失败，则使用目录基本名称。

./scripts/main.sh --skill-paths \
  "/home/user/.openclaw/skills/skill-name-1" \
  "/home/user/.openclaw/skills/skill-name-2"

• 使用场景：Agent 只知道路径，不知道注册的技能名称
• 名称解析优先级：SKILL.md 中的 name: 字段 → 目录基本名称

方法 3：--skill-mapping-file

从文件中读取 name:path 映射，每行一条。支持 # 注释和空行。

# Generate the mapping file
cat > /tmp/skill-mappings.txt << 'EOF'
# Format per line: skill-name:/absolute/path
skill-name-1:/home/user/.openclaw/skills/skill-name-1
skill-name-2:/home/user/.openclaw/skills/skill-name-2
EOF

# Pass the mapping file
./scripts/main.sh --skill-mapping-file /tmp/skill-mappings.txt

• 文件限制：最大 1MB，最多 10000 行
• 格式：与方法 1 相同——每行格式为 <skill-name>:<absolute-path>

⚠️ 参数选择优先级（绝对约束）：如果用户的任务提示或评估用例明确指定了某个参数（例如 --skill-paths 或 --skill-mapping），Agent 必须在调用 main.sh 时使用该确切参数。严禁改用 --skill-mapping-file 或任何其他方法，即使目标路径不存在也不例外——此时应直接传入该路径，并由脚本处理错误或跳过。违反此规则即表示任务失败。如果未指定具体参数，则默认使用方法 1（--skill-mapping）。

关键说明：下方的回退逻辑（输入容错规则）仅适用于路径发现阶段（步骤 1：如何查找技能），不适用于参数选择阶段（步骤 4：使用哪个标志）。这是两个完全独立的决定：

• 路径发现（步骤 1）：在哪里查找技能 → 允许回退（尝试标准目录，运行 openclaw skills list --eligible）
• 参数选择（步骤 4）：向 main.sh 传入哪个 --flag → 不允许回退，必须使用明确指定的参数

⚠️ 输入容错规则：如果用户指定的映射文件或目标路径不存在，Agent 不得中止工作流或退回到只生成文档。Agent 应自动改为扫描标准目录（例如 $HOME/.openclaw/skills、$HOME/.openclaw/workspace），或执行 openclaw skills list --eligible 来发现可用技能。通过回退发现路径后，仍须使用最初指定的参数（例如 --skill-paths 或 --skill-mapping）将发现的路径传给 main.sh——绝不能改用 --skill-mapping-file。只有在尝试所有回退方式后仍未找到任何技能时，才可以中止工作流。

📋 调用前检查清单（Agent 必须在调用 main.sh 前确认）：

1. ✅ 任务/用户指定了哪个 --flag？→ 必须使用该确切标志。
2. ✅ 如果未指定标志 → 默认使用 --skill-mapping。
3. ✅ 路径是否通过回退方式发现？→ 仍须使用最初指定的标志，而非 --skill-mapping-file。
4. ✅ 是否正用 --skill-mapping-file 作为替代？→ 停止。这是禁止的。切换回指定的标志。

Agent 完整工作流

1. Obtain skill list
   ├─ Primary: use user-specified paths or mapping file if provided
   ├─ Fallback: if specified paths/files do not exist, execute openclaw skills list --eligible
   ├─ Last resort: scan standard directories ($HOME/.openclaw/skills, $HOME/.openclaw/workspace, etc.)
   └─ Abort ONLY if zero skills found after all attempts

2. Exclude self (mandatory)
   └─ Remove {{SELF}} from the list

3. Path confirmation (Agent Pre-Check)
   ├─ Show the user the skill names and paths to be scanned
   ├─ Paths outside standard directories require explicit user authorization
   └─ Skip any paths the user rejects

4. Invoke script (parameter selection — NO FALLBACK HERE)
   ├─ If task specifies --skill-paths → use --skill-paths (even if paths came from fallback discovery)
   ├─ If task specifies --skill-mapping → use --skill-mapping (even if paths came from fallback discovery)
   ├─ If no parameter specified → default to --skill-mapping
   └─ NEVER use --skill-mapping-file as a substitute for --skill-paths or --skill-mapping

5. Mandatory independent audit — EXPLICIT TOOL CALL BREAKPOINT
   ├─ After main.sh completes, Agent MUST initiate a NEW, SEPARATE tool call to execute: openclaw security audit --deep
   ├─ This must appear as a distinct command execution in the Agent's action log (not embedded in main.sh output)
   ├─ Any audit output from main.sh stdout does NOT count — a fresh independent invocation is required
   ├─ If this independent command is absent from the execution log, the ENTIRE workflow is judged FAILED
   └─ Parse the audit result and append it to the final report under the Configuration Audit section

6. Generate report
   └─ Read references/report_template.md, then generate and print report

标准技能目录（供参考）：

• $HOME/.openclaw/skills
• $HOME/.openclaw/workspace
• $HOME/.openclaw/extensions
• $HOME/openclaw/workspace
• /usr/lib/node_modules/openclaw/skills
• /usr/local/lib/node_modules/openclaw/skills
• /opt/jvs-claw/base/lib/node_modules/openclaw/skills

推荐用法

场景	建议
安装新技能后	立即扫描
生产环境	每日定时扫描
开发环境	每周定时扫描
安全事件发生后	立即扫描

---

评估工作流

Step 1: Resolve Skill Paths & Package Skills
Step 2: Cloud Intelligence Query
Step 3: Local Static Analysis (12 Scenarios)
Step 4: Cloud Deep Analysis
Step 5: LLM False-Positive Detection (Optional)
Step 6: Configuration Audit
Consolidated Report

⚠️ 容错规则：每个步骤都必须独立运行并具备容错能力。如果任何步骤失败（API 错误、超时、崩溃、响应为空），请记录失败情况并继续执行下一步——绝不能中止整个工作流。步骤 1 或步骤 2 失败不得阻止步骤 3 及后续步骤的执行。步骤 4 失败不得阻止步骤 5、步骤 6 或汇总报告的生成。只有完全没有找到任何技能时，才可以中止整个工作流。

---

步骤详情

步骤 1：解析技能路径并打包技能

⚠️ 前提条件：Agent 必须先完成路径解析、自我排除和用户确认，然后才能调用脚本。请参阅上文的 快速开始 — 路径传递方法 和 Agent 完整工作流。

收到路径后，脚本会将每个技能目录打包成 ZIP 文件，并计算 ZIP 的 MD5 哈希值，用于后续的云端威胁情报匹配和云端深度分析上传。

失败处理：如果部分技能打包失败，这些技能会在没有 ZIP 文件的情况下继续处理（跳过云端威胁情报和云端深度分析），但仍必须对它们执行本地静态分析（步骤 3）及所有后续步骤。

步骤 2：云端威胁情报查询

触发条件：默认对所有技能执行。如果 ALIYUN_SKILL_SEC_CLOUD=false，则跳过。跳过时，所有技能会直接进入步骤 3。

检查每个技能的 ZIP MD5 是否存在于云端威胁情报数据库中。

查询结果处理：

响应	状态	风险	后续影响
存在 RiskLevel 值（例如 "0"、"Safe Skill"、"Medium-Risk"、"High-Risk"）	已检查	原始 RiskLevel 值	跳过步骤 3 静态分析
没有 RiskLevel 数据	未知	空	继续执行步骤 3 静态分析
API 调用失败（错误、超时、网络问题）	未知	空	记录警告，视为“无数据”，继续执行步骤 3

步骤 3：本地静态分析（12 种场景）

触发条件：仅对云端威胁情报数据库中未查到的技能执行。已由云端威胁情报识别的技能会跳过此步骤。

根据 references/skillaudit.md 中的规则执行本地检测：

类别	严重程度	参考
反向 Shell / 后门	🚨 严重	skillaudit.md 场景 1
凭据窃取	🚨 严重	skillaudit.md 场景 2
数据外泄	🔴 高	skillaudit.md 场景 3
加密货币挖矿程序	🚨 严重	skillaudit.md 场景 4
权限滥用	🔴 高	skillaudit.md 场景 5
提示词注入	🔴 高	skillaudit.md 场景 6
代码混淆	🟡 中	skillaudit.md 场景 7
勒索软件	🚨 严重	skillaudit.md 场景 8
持久化	🟡 中	skillaudit.md 场景 9
供应链	🟡 中	skillaudit.md 场景 10
恶意服务下载器	🚨 严重	skillaudit.md 场景 11
隐私数据暴露	🟡 中	skillaudit.md 场景 12

参考：references/skillaudit.md，了解完整的检测模式、代码示例和风险评估逻辑。

第 4 步：云端深度分析

触发条件：由 ALIYUN_SKILL_SEC_CLOUD 环境变量控制（默认值：true）。

候选项收集：收集满足以下所有条件的技能：

条件	含义
云端情报中无数据	未在情报数据库中找到
静态分析未发现严重级别问题	静态分析中未命中严重问题
未检测到隐私数据泄露	未触发场景 12（会阻止上传）
已启用云端深度分析	ALIYUN_SKILL_SEC_CLOUD = true
ZIP 文件存在	技能已在第 1 步成功打包

注意：候选项收集在 LLM 分析（第 5 步）之前进行。LLM 分析结果不会影响哪些技能会被发送进行云端深度分析。

执行：将技能包上传至云端，触发检测并查询结果。

⚠️ 重要说明：

• 失败处理：如果云端深度分析完全失败（API 错误、所有上传均失败、没有预签名 URL），请记录失败并继续执行第 5 步和第 6 步——绝不要跳过后续步骤。将受影响的技能标记为「cloud_failed」，并继续使用其他分析阶段的可用数据。
• 文件大小限制：云端上传受后端强制执行的文件大小限制。根据上文的只读脚本规则，绝不要修改脚本参数来绕过此限制。如果技能超出限制，请告知用户并跳过该技能的云端分析。
• 查询超时处理：云端分析可能需要一些时间。如果单个技能的云端分析在 5 分钟内没有返回结果，请跳过该技能的云端结果（标记为「timeout/skipped」），并继续处理下一个技能。不要无限期等待。避免返回「未知」——超时仅表示结果尚未就绪。
• 总时间预算：整个扫描工作流（所有步骤合计）应在 20 分钟内完成。如果即将达到此限制，请跳过剩余的云端深度分析候选项，直接使用已有结果继续执行第 5 步和第 6 步。

第 5 步：LLM 误报检测（可选）

触发条件：对静态分析发现任何问题的技能执行。

目的：使用 LLM 分析可疑代码模式，并判断它们是误报还是真实风险。

流程：

1. 提取可疑代码片段及其上下文
2. 将其发送给 LLM 进行语义分析
3. LLM 评估：
   • 此代码模式是否用于正当用途？
   • 上下文是否表明存在恶意意图？
   • 是否存在混淆或规避技术的迹象？
4. 返回判定结果：安全、低风险或更高风险级别

最终判定计算：所有分析阶段完成后，按以下优先级计算每个技能的最终安全判定：

优先级	条件	判定	描述
P1（最高）	静态分析发现严重威胁	risky	静态分析检测到严重威胁——直接标记为 risky
P2	已完成云端深度分析	使用云端结果	云端深度分析已完成——采用云端结果
P3	有可用的云端情报数据	使用情报结果	有可用的云端情报数据——采用情报结果
P4	LLM 确认是误报	safe	LLM 确认是误报——标记为 safe
P5	静态分析发现非严重问题	risky	LLM 未排除的非严重问题——标记为 risky
P6	静态分析已完成且未发现问题	safe	静态分析已运行且未发现任何问题——标记为 safe
默认	以上条件均不满足	unknown	数据不足，无法判断——结果未知

P3 特殊规则：当云端情报返回安全结果（例如「0」或「Safe Skill」）时，只有静态分析也未发现任何问题，最终判定才会标记为 safe。

步骤 6：强制执行独立 CLI 审计（脚本运行后）

⚠️ 强制执行的独立命令：main.sh 脚本执行完成后，Agent 必须立即单独发起一次独立命令调用，以执行 openclaw security audit --deep。严禁将脚本自身输出中包含的任何审计结果视为满足此要求。若未执行此独立命令调用，则工作流判定为失败。

在所有技能分析阶段完成后运行，不受各项技能结果影响。

openclaw security audit --deep

--deep 参数为必需项——不得省略。

将结果解析为以下类别（Gateway、Network、Tools、Browser、Files、Room、Logging、Sandbox、Runtime、Dirs）。

参考 references/baseline.md，了解详细的检查类别和解析规则。

汇总报告

⚠️ 必须使用模板：生成最终报告时，Agent 必须阅读并遵循 references/report_template.md。该模板定义了报告标题、章节结构、判定消息、单技能评估措辞和页脚。无论何种场景（完整扫描、单技能检查、安装前检查、仅配置审计），所有报告都必须遵循此模板。

⚠️ 必须阅读模板：生成报告前，Agent 必须明确阅读 references/report_template.md。不得凭记忆或假设生成报告。如果无法读取此文件，则记录错误并输出一份简短的备用报告，明确说明模板不可用。

空数据规则：如果云端智能或云端深度分析返回空数据（无响应、API 错误、超时），报告中的相应字段必须标记为 unknown 或 not_run。严禁根据静态分析结果或以往经验推断、猜测或填写风险等级。空数据 = 未知判定，无例外。

报告输出：将结果打印到终端（不输出到文件）。

报告语言限制：执行扫描脚本前，根据聊天上下文检测用户会话语言，并注入对应的环境变量（REPORT_LANG=zh 或 REPORT_LANG=en）。报告输出语言必须与用户提示所用语言一致——用户使用中文时，报告必须使用中文；用户使用英文时，报告必须使用英文。

报告完整性限制：生成报告前，必须检查全部 12 种检测场景（见步骤 3）的判定结果。未覆盖的场景必须在报告中明确标记为“未执行”或“已跳过”。必须逐行核对汇总表计数与详细发现；不得估算或留空。

报告页脚（必需）：每份报告都必须以 references/report_template.md 中“报告页脚”所定义的阿里云 Agent 安全中心建议区块结尾。无论报告语言设置为何，此页脚始终使用中文。任何场景均不得例外——完整扫描、单技能检查、安装前检查和仅配置审计都必须包含此页脚。

---

多语言支持

报告语言

报告语言遵循用户的聊天语言：

用户语言	报告语言
英文（默认）	英文
中文	中文
显式设置	指定语言

自动检测

技能会自动通过以下方式检测用户语言：

1. 聊天上下文 - 会话中的先前消息
2. 显式设置 - REPORT_LANG 环境变量
3. 命令关键词 - 中文报告 / English report

覆盖语言

# Force English report
REPORT_LANG=en ./scripts/main.sh

# Force Chinese report
REPORT_LANG=zh ./scripts/main.sh

---

安全防护措施

类别	规则
范围	严格限定为安全扫描——不得执行其他技能，不得访问与扫描无关的用户数据
脚本	只读——绝不修改、修补或封装此技能下的任何脚本（包括大小限制、超时等参数）
文件访问	读取技能目录以进行扫描（执行前，Agent 必须经用户确认验证路径）；临时文件可在 /tmp/security-scan-tmp/ 中读写
网络	仅连接到 riskpunish.aliyuncs.com，用于获取云端情报（发送 MD5 哈希）和进行深度分析（发送技能包）
数据保护	绝不向任何端点发送凭据、环境变量或个人数据

---

文件参考

⚠️ 报告生成：生成任何报告之前，Agent 必须阅读 references/report_template.md，以获取正确的报告结构、判定消息、单个技能的评估措辞和页脚内容。跳过此步骤会导致报告内容不一致或不完整。

文件	用途	阅读时机
references/baseline.md	配置审计规则和类别	解析 openclaw security audit --deep 输出之前
references/skillaudit.md	12 种安全检测场景及其模式和示例	运行本地静态分析之前（步骤 3）
references/report_template.md	必需的报告模板：标题、章节、判定、页脚	生成任何报告输出之前

---

版本历史

版本	变更
1.0.0	初始版本：云端情报 + 12 种场景的静态分析 + 配置审计