skill-scanner

捆绑的上游支持文件

支持文件位于相对于技能目录的路径下。其固定来源、许可证、哈希值和导入变更请参见 UPSTREAM-NOTICE.md。

技能安全扫描器

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

请显式指定已安装的技能目录。使用包含 PyYAML 且已审核的 Python 环境运行捆绑的辅助脚本；无需将工作目录设为仓库根目录，也无需隐式下载依赖项。

使用时机

• 采用技能之前，需要评估其是否存在提示词注入、恶意代码、权限过宽或供应链风险。
• 希望对技能目录进行静态扫描并结合人工审核。
• 需要判断技能是否足够安全，可以在 Agent 环境中信任它。

捆绑脚本

scripts/scan_skill.py

静态分析扫描器，用于检测确定性模式。输出结构化 JSON（skill-scanner.locators.v2）。报告包含固定的问题描述、本地文件／行定位信息、计数、识别到的工具，以及元数据字段的存在情况和类型。报告不包含原始元数据值、源代码片段、解码后的载荷、命令、符号链接目标和完整 URL。请根据报告中的位置私下检查这些内容。相对文件名、所选目录标识符和 URL 主机名仍会作为可见标识符显示；该报告并非敏感名称的匿名化工具。不支持的输入会被标记为不完整，而非安全。

python3 "<installed-skill-dir>/scripts/scan_skill.py" "<authorized-inert-skill-directory>"

返回包含发现项、URL 主机名／行定位信息、结构信息和严重性计数的 JSON。脚本以机械方式捕获模式——你的工作是评估其意图并排除误报。

扫描器覆盖范围与报告隐私

请使用私密、无副作用的快照：此辅助脚本用于静态检查，并非执行沙箱。它会拒绝最终路径组件为符号链接或非普通文件的路径，并限制文件大小为 1 MiB、目录树大小为 1,000 个文件／16 MiB。无法安全地以禁止跟随符号链接的方式打开文件的主机，会报告覆盖范围不完整，而非悄悄跟随链接。会纳入嵌套的普通文本文件；二进制／不可读输入则会被明确列为覆盖缺口。扫描出错或覆盖范围不完整时，退出状态为非零，而非通过。

报告会省略源载荷，而非依赖对所有秘密格式的识别。可见的文件名和主机名仍可能是机密标识符；分享前请在本地检查报告。不会执行目标脚本、生命周期钩子、测试或外部 URL。熟悉某个领域或存在词面重合，并不等同于语义审核，也不构成合并授权。

工作流

阶段 1：输入与发现

确定扫描目标：

• 如果用户提供了技能目录路径，请直接使用
• 如果用户指定了技能名称，请在 plugins/*/skills/<name>/ 或 .claude/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：自动静态扫描

运行捆绑的扫描器：

python3 "<installed-skill-dir>/scripts/scan_skill.py" "<authorized-inert-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/ 或任何 Agent 配置目录

范围蔓延：

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

信息收集：

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

第 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 — 高风险，接近完全访问权限

置信度等级

等级	标准	处理方式
HIGH	模式已确认，且恶意意图明确	报告并标明严重程度
MEDIUM	存在可疑模式，但意图不明确	标注为“需要验证”
LOW	仅属理论可能或最佳实践建议	不要报告

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

输出格式

## Skill Security Scan: [Skill Name]

### Summary
- **Findings**: X (Y Critical, Z High, ...)
- **Risk Level**: Critical / High / Medium / Low / No pattern matches
- **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**: [local file/line and matched pattern; omit secret-bearing source snippets]
- **Risk**: [What could happen]
- **Remediation**: [How to fix]

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

### Assessment
[Scoped review recommendation / More evidence required / Do not adopt]
[Brief justification for the assessment]

风险等级判定：

• Critical：存在任何高置信度的严重发现（提示词注入、凭据窃取、数据泄露）
• High：存在高置信度的高严重性发现，或多项中等程度发现
• Medium：存在中等置信度的发现，或轻微的权限问题
• Low：只有最佳实践建议
• No pattern matches：在报告涵盖范围内未匹配到任何模式；这并不能证明其安全或完整

参考文件

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

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。