Skill Scanner架构全解：两阶段扫描流水线如何协同11个检测引擎

【免费下载链接】skill-scannerSecurity Scanner for Agent Skills项目地址: https://gitcode.com/gh_mirrors/sk/skill-scanner

Skill Scanner是一款面向 AI Agent Skills（智能体技能包）的开源安全扫描器。它用一条两阶段扫描流水线串联起11 个检测引擎——先由确定性引擎快速完成模式匹配与行为分析，再让 LLM 分析引擎带着第一阶段的线索做语义级研判。本文将带你从零看懂这套架构：为什么这样分阶段、每个引擎负责什么、以及如何按需组合使用。

为什么 Agent Skills 需要专业安全扫描

Agent Skills 通常由SKILL.md指令文件和配套脚本、二进制文件组成，会被 AI Agent 直接执行。一个恶意技能包可能藏有提示注入、数据外传指令、混淆脚本甚至二进制载荷。

单靠一种检测手段总有盲区：正则签名抓不到"语义上有害但字面上干净"的指令，LLM 又可能误报普通代码。Skill Scanner 的答案是分层多引擎协同——确定性引擎负责"快而准"，语义引擎负责"深而全"，两者通过流水线上下文接力。

架构总览：一张图看懂 Skill Scanner

整个系统由三部分组成：

• 入口层：CLI（skill-scanner）、FastAPI REST API、Pre-commit Hook，三者共用同一套分析器工厂，保证行为一致
• 核心引擎：SkillScanner编排器（skill_scanner/core/scanner.py）+SkillLoader加载器（skill_scanner/core/loader.py）+ 可插拔的分析器集合
• 数据层：核心规则包（YAML 签名 + YARA 规则 + Python 检查，位于 skill_scanner/data/packs/core/）、LLM 提示词模板（skill_scanner/data/prompts/）以及策略预设文件

分析器的组装由唯一的"真相来源"——skill_scanner/core/analyzer_factory.py 完成：build_core_analyzers()按策略构建核心引擎，build_analyzers()再按命令行/API 开关追加可选引擎。

完整的架构说明见官方文档 docs/architecture/index.md。

两阶段扫描流水线：从加载到报告

流水线定义在 docs/architecture/scanning-pipeline.md，共 7 个阶段。

阶段 0：加载与预处理

SkillLoader负责验证技能目录、解析SKILL.mdfrontmatter、递归发现文件并分类（Python/Bash/Markdown/二进制）；ContentExtractor则安全地解包技能中内嵌的 ZIP/TAR 归档，同时防御 ZIP 炸弹、路径穿越、符号链接等经典解包攻击——解包结果直接并入分析范围。

阶段 1：8 个确定性引擎火力全开

所有非 LLM 引擎在这一阶段独立运行，包括策略驱动的核心引擎和按开关启用的可选引擎：

静态引擎是"主力"，内部按序执行约 20 轮检查（清单校验 → 指令体签名 → 动态执行检测 → Unicode 走私 → YARA 扫描 → 文档/PDF/Office 结构分析等），详见 docs/architecture/analyzers/static-analyzer.md。

阶段 1.5：CEL 决策层 + 裁决器

第一阶段的候选发现会先做精确去重，然后投影为有界的ScanFacts，交由CEL 决策层做门控。它只能"保留/抑制"已有的候选发现，不能凭空造出告警，投影不完整或运行出错时一律 fail-open（放行），详见 docs/architecture/cel-decision-layer.md。

紧接着的 **Adjudicator（裁决器）**会用 LLM 复核纯字面正则命中的高严重度发现，只降不升——避免一条错误的高危误报进入下一阶段后被 LLM"引用放大"。

阶段 2：带"上下文增强"的 LLM 引擎

这是两阶段设计最巧妙的地方。LLM 引擎（LLM Analyzer）和 Meta 引擎（Meta-Analyzer）刻意延后执行，并先接收一份由阶段 1 结果构建的增强上下文：

• 文件清单：总文件数、类型分布、未被引用的脚本
• 魔术字节不匹配清单（文件扩展名与实际内容不符）
• 静态引擎的前 10 条 CRITICAL/HIGH 级发现摘要
• 可分析性评分与清单能力声明

也就是说，LLM 不是"盲审"，而是拿着确定性引擎的线索做语义级意图分析（如社会工程、隐蔽数据外传、多步攻击），而 Meta 引擎则做最后一道误报过滤与优先级排序，复核所有前序发现。

后处理：结果净化的最后闸门

分析结束并非终点，还要依次执行：VirusTotal 已验证二进制的去重抑制 → 禁用规则过滤 → 严重度覆盖 →可分析性评分（扫描器看不到的内容越多，分数越低，fail-closed 策略下会生成UNANALYZABLE_BINARY告警）→ 发现归一化与去重 → 共现元数据标注 → 策略指纹附加。最后生成ScanResult，输出为 summary/JSON/Markdown/Table/SARIF/HTML 六种格式之一。

11 个检测引擎能力矩阵：谁抓什么威胁

11 个引擎的分工与威胁类别覆盖如下（✓ 表示可产出该类发现，来源 docs/architecture/analyzers/index.md）：

同一类别有多个引擎覆盖，意味着更强的检测纵深：一个引擎漏掉的模式，另一个可能接住。

还有一个特殊角色——Cross-Skill Scanner（跨技能扫描器）。它不在单技能流水线内运行，而是在scan-all --check-overlap时对整个技能集合做关联分析，识别数据接力、共享外部 URL、互补触发器等同谋攻击模式，接口见 skill_scanner/core/analyzers/cross_skill_scanner.py。

如何按需组合：从快速 CI 到最大覆盖

11 个引擎并非全部强开。核心引擎随策略默认运行，可选引擎按需激活：

策略系统（skill_scanner/core/scan_policy.py）还提供 balanced（默认）/strict/permissive 三套预设，外加严重度覆盖、禁用规则等 14 个可配置分区，无需改代码即可调优。

关键源码路径速查

想深入源码时，建议按此顺序阅读：

• 流水线编排：skill_scanner/core/scanner.py（两阶段循环的核心）
• 分析器工厂：skill_scanner/core/analyzer_factory.py
• 分析器基类：skill_scanner/core/analyzers/base.py
• LLM 引擎：skill_scanner/core/analyzers/llm_analyzer.py
• 行为引擎：skill_scanner/core/analyzers/behavioral_analyzer.py
• 扩展指南（自定义规则）：docs/architecture/analyzers/writing-custom-rules.md
• 功能总览与威胁能力矩阵：docs/features/index.md

总结

Skill Scanner 的架构精髓可以概括为一句话：让确定性引擎先跑、把线索交给语义引擎，再用决策层和裁决器双向降噪。两阶段流水线让 11 个检测引擎各司其职又彼此增强——阶段 1 提供速度与证据，阶段 2 提供深度与语义，CEL 层与 Adjudicator 守住精度，可分析性评分兜住盲区。对新手而言，记住"核心三引擎默认开、可选引擎按需开"就足以开始使用；对进阶用户，源码中的SkillScanner编排逻辑是理解全貌的最佳入口。

【免费下载链接】skill-scannerSecurity Scanner for Agent Skills项目地址: https://gitcode.com/gh_mirrors/sk/skill-scanner