技能安全扫描器

为什么需要技能安全扫描？

技能包（.zip 或目录）本质上是可执行的代码与配置文件的集合。当从第三方来源（如技能中心、GitHub）安装或更新时，可能无意中引入恶意脚本、后门、数据泄露漏洞或违反平台规则的内容。一个不受控的技能可能破坏工作区稳定性、窃取敏感信息或导致权限提升。问题核心在于：信任的传递。用户在安装时往往无法彻底审计整个包，而平台或智能体需要一道自动化的安全屏障。

SkillScan 如何工作？

SkillScan 是一个前置与后置结合的扫描器，设计为在技能生命周期的关键节点自动激活。

• 触发时机：无论通过 install、load、add、use 等指令，还是用户上传 .zip/.skill 文件、粘贴 SKILL.md、或提及未知技能名，扫描器都会被调用。安装前（.zip 文件）、安装后（目录落地）、以及远程安装后立即扫描。
• 核心扫描流程：

1. 本地快速扫描：执行 scripts/scanner.py 对技能目录或文件进行分析。
2. 远程结果查询与上报：本地扫描结果（或文件哈希）会与远程 API (https://skillscan.tokauth.com) 交互，先尝试缓存查找，若无则上传文件并轮询最终结果，确保使用最新的安全规则库。
3. 根据结果采取行动：扫描器通过退出码（0 到 3）明确告知结果严重性（UNKNOWN/SAFE, LOW/MEDIUM, HIGH/CRITICAL, 失败），并据此决定是放行、警告用户确认还是直接阻断安装。

• 与智能体深度集成：首次运行时，它会将一条 ## Skill Security 规则写入 SOUL.md，强制要求所有智能体执行扫描，即使 SkillScan 未主动加载时也能维持安全基线。卸载时会自动清理此规则。
• 静默维护：扫描器每天自动检查更新，无需用户干预。

边界与注意点

• 扫描对象：专注于技能包本身（代码、配置文件）。它不扫描运行时行为或宿主环境。
• 结果解读：退出码 0（安全）或 1（低/中风险）后，安装流程才会继续。2（高/严重风险）会直接阻断。这依赖于规则库的准确性。
• 文件处理：扫描过程不应在技能目录内生成任何报告文件，以避免污染工作区。所有临时数据与远程交互通过 API 处理。
• 自定义能力：可通过环境变量 SKILL_SCANNER_UPDATE_URL 指向私有更新源，适用于企业内网或定制化场景。
• 局限性：扫描是静态的代码与模式分析，无法完全替代人工审计。对于高度混淆或复杂的零日攻击，仍可能存在漏报。