test0413-6348

一个面向安全的技能，用于安全地管理 OpenClaw 技能。本包包含可执行的 Python 脚本（非纯指令型），具备六大核心能力：

1. 威胁扫描（静态分析）
2. 仅追加式审计日志（本地 NDJSON 格式）
3. 技能监控与通知（变更时推送告警）
4. 文件级差异 + 内容差异（基于 git 快照）
5. 基线审批机制（已批准技能不再重复告警）
6. 语义分析（危险函数识别 + 能力分析）

该技能执行的是对被审计技能的 静态分析 —— 它 不会执行被审计技能自身的代码。但审计工具本身会执行 本地可信命令/子进程，例如 git、Python 辅助脚本，以及为快照生成、差异比对和通知生成所必需的受控本地进程调用。

依赖要求

• Python ≥ 3.9，仅使用标准库（无第三方依赖）
• git（必需，用于内容差异快照及本地仓库历史）
• 审计工具自身需运行于常规本地 shell / 进程环境中，以支持受控子进程执行
• 详见 scripts/requirements.txt

核心能力

1) 威胁扫描（静态风险分析）

skills_audit.py 对已安装技能目录执行静态检查：

输出字段：

• risk.level：low | medium | high | extreme
• risk.decision：allow | allow_with_caution | require_sandbox | deny
• risk.risk_signals[]：证据（文件路径 + 代码片段）
• risk.network.domains[]：提取出的域名列表
• risk.source：local

2) 审计日志（仅追加式 NDJSON）

所有检测结果均以 NDJSON 格式追加写入：

• ~/.openclaw/skills-audit/logs.ndjson

用于差异比对的状态快照：

• ~/.openclaw/skills-audit/state.json

日志结构由 log-template.json 定义。关键字段说明：

• sha256：SKILL.md 文件的 SHA-256 哈希值（完整性校验字段）
• diff：git 提交信息 + 各文件统计信息
• file_changes：文件级增/删/改列表
• approved：基线审批状态

3) 技能监控与推送通知

周期性监控 workspace/skills 目录下的新增、变更与删除操作。

• 无变更 → 不输出任何内容
• 检测到变更 → 发送一条通知
• 基线已批准且未变更的技能将从通知中排除

通知模板位于：templates/notify.txt（自定义方法见 templates/README.md）。

4) 文件级差异 + 内容差异（Git 快照）

每次扫描均将 skills 目录快照保存至本地 git 仓库（~/.openclaw/skills-audit/snapshots/）：

• 每次扫描 = 一次 git commit
• 通过 git diff HEAD~1 HEAD 检测变更
• 通知中包含各文件变更摘要（+N -N 行数）

分级显示策略：

• ≤ 5 个文件变更：全部列出，含 +N -N 行数
• 6–20 个文件变更：显示前 3 个 + “X more omitted”
• > 20 个文件变更：显示前 3 个 + 省略 + ⚠️ 大规模变更警告
• > 8 个技能变更：高风险项展开，低风险项压缩

查看完整差异：

git -C ~/.openclaw/skills-audit/snapshots diff HEAD~1 HEAD
git -C ~/.openclaw/skills-audit/snapshots diff HEAD~1 HEAD -- skills//
git -C ~/.openclaw/skills-audit/snapshots log --oneline

6) 语义分析（危险函数 + 能力分析）

每次扫描还会在审计日志中生成 semantic_analysis 字段：

• 危险函数分析：检测如 eval、exec、os.system、subprocess 配合 shell=True、curl|sh、wget|bash 等模式
• 能力分析：推断技能是否具备网络、文件系统、进程执行、cron/调度器、git 或配置处理等能力
• 综合判定：分别评估执行能力风险与恶意意图风险；以语义意图作为首要决策维度，最终输出 level / decision / reason

说明：

• 当前实现为一种 本地 LLM 风格的启发式分析，不依赖外部模型
• 此为一项 强制规则：所有新增或变更的技能，在执行 skills_audit.py scan 时必须经过语义分析
• 若 semantic_analysis 缺失或无法生成有效结果，则扫描应失败，而非静默跳过
• 为降低自审计误报率，低信号文件（如规则配置、日志模板、技能文档、config/semantic-patterns.json）将从高权重危险函数评分中排除
• 风险规则扫描现区分命中上下文：real_execution / rule_sample / doc_example / config_sample
• 对于 skills_audit.py 自身，语义检测与风险扫描均优先聚焦真实执行路径，而非默认将模式字符串表视为危险执行
• 语义分析现已分离执行能力与恶意意图，因此常规工程能力不自动等同于恶意结果
• 受控本地调用（如 subprocess.run([...], shell=False) 且 argv 固定）被视为工程能力，而非自动归类为恶意意图
• 该字段设计为向前兼容，未来可无缝接入真实 LLM 支持的语义扫描器

5) 基线审批机制

通过 ~/.openclaw/skills-audit/baseline.json 管理已批准技能：

• 已批准技能（匹配 tree_sha256）将不再触发重复告警
• 任一文件变更将自动使审批失效 → 重新触发风险检测

python3 {baseDir}/scripts/skills_audit.py approve --skill weather --workspace 
python3 {baseDir}/scripts/skills_audit.py approve --all --workspace 
python3 {baseDir}/scripts/skills_audit.py baseline --list
python3 {baseDir}/scripts/skills_audit.py baseline --revoke --skill weather

初始化与手动监控配置（Agent 指令）

当 Agent 首次加载本技能时，可执行 本地初始化，但 不得自动创建 cron 任务。应引导用户显式创建监控：

1. 检查 ~/.openclaw/skills-audit/state.json 是否存在
2. 若不存在，则执行初始化：

   python3 {baseDir}/scripts/skills_audit.py init --workspace 
   

3. 检查是否存在 skills-audit-watch cron 任务（openclaw cron list）
4. 若不存在：
   • 禁止自动创建 cron
   • 提示用户可手动创建
   • 提供推荐命令示例（须由用户自行执行，或仅在获得用户明确授权后执行）：

   openclaw cron add 
     --name "skills-audit-watch" 
     --cron "*/1 * * * *" 
     --tz "Asia/Shanghai" 
     --session isolated 
     --message "python3 {baseDir}/scripts/skills_watch_and_notify.py --workspace " 
     --announce 
     --channel  
     --to 
   

5. 提醒用户在启用前验证推送目标，尤其当原始 diff 或大规模变更详情可能外发时
6. 不得默认将大规模原始 diff 推送至外部通道；应优先发送简洁摘要，详情按需提供

设计原则：skills-audit 负责扫描、日志记录与通知文本生成；调度与投递应由用户主导，而非默认自动创建。

查看变更详情（Agent 强制流程）

⚠️ 强制规则：当用户询问技能变更详情时，Agent 必须 使用 show 命令获取结构化变更数据。默认应先提供 安全摘要，而非直接向外发送完整原始 diff。

触发短语（用户可能表达为）：

• “what changed” / “show diff” / “what's different” / “change details”
• “具体改了什么” / “哪里变了” / “看一下变更”
• 任何请求 diff / 变更 / 修改详情的表述

固定执行流程（不可跳过）：

1. 若用户提及具体技能：

   python3 {baseDir}/scripts/skills_audit.py show --skill 
   

2. 若未指定具体技能：

   python3 {baseDir}/scripts/skills_audit.py show
   

3. 默认仅发送基于 show 输出生成的 安全摘要（含变更文件、行数、主要变更点），避免对外暴露敏感 diff 内容
4. 仅当用户 明确要求原始/完整内容 时，才发送完整 show 输出，并应向用户警示：diff 中可能出现敏感信息
5. 查看历史变更，请使用 --commit-range：

   python3 {baseDir}/scripts/skills_audit.py show --commit-range HEAD~3..HEAD~2
   

禁止行为：

• ❌ 绕过结构化 show 输出路径，直接运行 git diff
• ❌ 默认向外通道发送原始完整 diff 内容且不加警告
• ❌ 自动向外部通道推送大规模原始变更内容
• ✅ 优先基于 show 提供安全摘要；仅在用户明确请求时提供完整原始内容

手动使用方式

初始化

python3 {baseDir}/scripts/skills_audit.py init --workspace /root/.openclaw/workspace

手动扫描

python3 {baseDir}/scripts/skills_audit.py scan --workspace /root/.openclaw/workspace --who user --channel local

本地通知测试

python3 {baseDir}/scripts/skills_watch_and_notify.py --workspace /root/.openclaw/workspace

安全注意事项

• 仅执行静态分析：审计过程中绝不运行未知技能代码。
• 当 risk.level 为 high 或 extreme 时，必须经人工审查或置于 sandbox 中执行。
• 调度任务请优先使用 OpenClaw 的 cron add / cron edit 命令。
• 完整性校验采用 SHA-256。