skill-scanner

技能安全扫描器

在采用 Agent 技能之前，扫描其安全问题。检测提示词注入、恶意代码、权限过度、机密泄露和供应链风险。

需要：用于 Python 包管理的 uv CLI，安装指南见 https://docs.astral.sh/uv/getting-started/installation/

重要：所有脚本都必须从仓库根目录运行。scripts/scan_skill.py 之类的脚本路径是相对于此技能的根目录（即包含此 SKILL.md 的目录），而不是相对于目标仓库。

捆绑脚本

scripts/scan_skill.py

静态分析扫描器，可检测确定性模式。输出结构化 JSON。

uv run scripts/scan_skill.py <skill-directory>

返回包含发现项、URL、结构信息和严重性计数的 JSON。脚本会机械地捕获模式——你的工作是评估其意图并筛除误报。

工作流

阶段 1：输入与发现

确定扫描目标：

• 如果用户提供了技能目录路径，直接使用该路径
• 如果用户指定了某项技能，先在 .agents/skills/<name>/ 下查找；然后再查找其他既定布局，例如：当仓库使用规范的根级技能树时，查找 skills/<name>/、.claude/skills/<name>/、plugins/*/skills/<name>/，或其他有明确既有范例的仓库管理技能根目录
• 如果用户说“扫描所有技能”，则查找所有 */SKILL.md 文件并逐一扫描

验证目标是否包含 SKILL.md 文件。列出技能结构：

ls -la <skill-directory>/
ls <skill-directory>/references/ 2>/dev/null
ls <skill-directory>/scripts/ 2>/dev/null

阶段 2：自动静态扫描

运行捆绑扫描器：

uv run scripts/scan_skill.py <skill-directory>

解析 JSON 输出。脚本会生成带有严重性级别、URL 分析和结构信息的发现项。将这些内容作为深入分析的线索。

备用方案：如果脚本运行失败，则使用参考文件中的 Grep 模式进行手动分析。

阶段 3：Frontmatter 验证

阅读 SKILL.md 并检查：

• 必填字段：必须包含 name 和 description
• 名称一致性：name 字段应与目录名称一致
• 工具评估：检查 allowed-tools——使用 Bash 是否合理？工具是否不受限制（*）？
• 模型覆盖：是否强制指定了某个模型？原因是什么？
• 描述质量：描述是否准确体现了该技能的功能？

阶段 4：提示词注入分析

加载 references/prompt-injection-patterns.md 以了解相关背景。

检查“提示词注入”类别中的扫描器发现项。对于每个发现项：

1. 阅读文件中的相关上下文
2. 判断该模式是在实施注入（恶意），还是在讨论／检测注入（合理）
3. 安全、测试或教育类技能通常会提及注入模式——这是预期行为

关键区别：在参考资料中列出注入模式的安全审查技能是在记录威胁，而不是发起攻击。只标记会对运行该技能的 Agent 生效的模式。

阶段 5：行为分析

此阶段仅由 Agent 执行——不进行模式匹配。阅读完整的 SKILL.md 指令并评估：

描述与指令是否一致：

• 描述是否符合指令实际要求 Agent 执行的操作？
• 如果某个技能描述为“代码格式化工具”，却指示 Agent 读取 ~/.ssh，则两者不一致

配置／记忆投毒：

• 要求修改 CLAUDE.md、MEMORY.md、settings.json、.mcp.json 或钩子配置的指令
• 要求将自身加入允许列表或自动批准权限的指令
• 写入 ~/.claude/、~/.agents/ 或任何 Agent 配置目录
• 会向全局配置文件追加内容的脚本——即使移除技能，被投毒的指令仍会保留

范围蔓延：

• 超出技能声明用途的指令
• 不必要的数据收集（读取与技能功能无关的文件）
• 要求安装描述中未提及的其他技能、插件或依赖项

信息收集：

• 读取超出所需范围的环境变量
• 列出技能范围以外的目录内容
• 不必要地访问 Git 历史记录、凭据或用户数据

结构性攻击（检查扫描器输出中是否存在以下内容）：

• 符号链接：解析后指向技能目录外部的文件——可将读取 ~/.ssh/id_rsa、~/.aws/credentials 等行为伪装成读取“示例”文件
• Frontmatter 钩子：YAML 中的 PostToolUse/PreToolUse 钩子——会自动执行 shell 命令，模型无法阻止
• !command`` 语法：在技能加载时、模型看到提示词之前，于模板展开期间运行 shell 命令
• 测试文件：conftest.py、test_*.py、*.test.js——测试运行器会自动发现并执行这些文件，作为 pytest 或 npm test 的副作用
• npm 生命周期钩子：捆绑的 package.json 中的 postinstall 脚本——会在 npm install 时自动运行
• 图像元数据：PNG 文件中元数据块（tEXt/iTXt）里的文本——多模态大模型可从图像元数据中读取隐藏指令

阶段 6：脚本分析

如果技能包含 scripts/ 目录：

1. 加载 references/dangerous-code-patterns.md 以了解相关背景
2. 完整阅读每个脚本文件（不得跳过）
3. 检查“恶意代码”类别中的扫描器发现
4. 对每项发现进行评估：
   • 数据外泄：脚本是否向外部 URL 发送数据？发送了哪些数据？
   • 反向 Shell：是否存在重定向 I/O 的套接字连接
   • 凭据窃取：是否读取 SSH 密钥、.env 文件或环境变量中的令牌
   • 危险执行：是否使用带动态输入的 eval/exec，或带插值的 shell=True
   • 配置修改：是否写入 Agent 设置、shell 配置或 Git 钩子
5. 检查 PEP 723 dependencies——它们是否为正当、知名的软件包？
6. 确认脚本行为与 SKILL.md 对其功能的描述一致

正当模式：调用 gh CLI、使用 git 命令、读取项目文件、将 JSON 输出到 stdout，通常都是技能脚本的正常行为。

阶段 7：供应链评估

审查扫描器输出中的 URL，以及脚本中发现的任何其他 URL：

• 可信域名：GitHub、PyPI、官方文档——通常可信
• 不可信域名：未知域名、个人网站、URL 缩短服务——标记以供审核
• 远程指令加载：任何用于获取内容并执行或将其解释为指令的 URL，风险都很高
• 依赖项下载：在运行时下载并执行二进制文件或代码的脚本
• 无法验证的来源：引用标准注册表中不存在的软件包或工具

阶段 8：权限分析

加载 references/permission-analysis.md，查看工具风险矩阵。

评估：

• 最小权限：实际是否使用了所有已授予的工具？
• 工具合理性：技能正文是否提及需要使用每项工具的操作？
• 风险级别：使用参考文件中的分级系统评定整体权限配置

评估示例：

• Read Grep Glob — 低风险，只读分析技能
• Read Grep Glob Bash — 中风险，需要说明使用 Bash 的理由（例如运行捆绑脚本）
• Read Grep Glob Bash Write Edit WebFetch Task — 高风险，接近完全访问权限

置信度级别

级别	标准	操作
高	已确认模式 + 恶意意图明显	报告并注明严重程度
中	存在可疑模式，意图不明确	标记为“需要核实”
低	仅为理论情况或最佳实践建议	不予报告

防范误报至关重要。 最大的风险是因为安全技能提到了攻击模式，就将其误判为恶意内容。报告前务必评估其意图。

输出格式

## Skill Security Scan: [Skill Name]

### Summary
- **Findings**: X (Y Critical, Z High, ...)
- **Risk Level**: Critical / High / Medium / Low / Clean
- **Skill Structure**: SKILL.md only / +references / +scripts / full

### Findings

#### [SKILL-SEC-001] [Finding Type] (Severity)
- **Location**: `SKILL.md:42` or `scripts/tool.py:15`
- **Confidence**: High
- **Category**: Prompt Injection / Malicious Code / Excessive Permissions / Secret Exposure / Supply Chain / Validation
- **Issue**: [What was found]
- **Evidence**: [code snippet]
- **Risk**: [What could happen]
- **Remediation**: [How to fix]

### Needs Verification
[Medium-confidence items needing human review]

### Assessment
[Safe to install / Install with caution / Do not install]
[Brief justification for the assessment]

风险级别判定：

• 严重：存在任何高置信度的严重发现（提示词注入、凭据窃取、数据外泄）
• 高：存在高置信度的高严重性发现，或多个中置信度发现
• 中：存在中置信度发现，或轻微权限问题
• 低：仅有最佳实践建议
• 无风险：经过全面分析后未发现问题

参考文件

文件	用途
references/prompt-injection-patterns.md	注入模式、越狱、混淆技术、误报指南
references/dangerous-code-patterns.md	脚本安全模式：数据外泄、Shell、凭据窃取、eval/exec
references/permission-analysis.md	工具风险分级、最小权限方法、常见技能权限配置