SkillSpector 2.5.0 技术解析Inspection Ledger 执行完整性记账与 V2 基线指纹迁移实战【免费下载链接】SkillSpectorSecurity scanner for AI agent skills. Detect vulnerabilities, malicious patterns, security risks, prompt injection, data exfiltration, and supply-chain risks in Claude Code, Codex, and MCP skills before you install them.项目地址: https://gitcode.com/GitHub_Trending/sk/SkillSpector本篇技术指南以 SkillSpector v2.5.0 发布说明为主体深入剖析本次版本的核心能力canonical inspection-ledger规范化检查台账执行完整性报告、JSON/SARIF 输出的execution_successful状态、递归扫描失败传播、CLI 退出码 2 的语义以及必须执行的 V2 基线指纹迁移。读完本文你将掌握如何让安全自动化区分正常零发现与扫描未可靠执行并能独立完成 v1 基线的升级与 JSON 集成适配。一、版本概览为什么 2.5.0 是一次可信度升级SkillSpector 2.5.0发布于 2026-07-24引入规范化 inspection-ledger 记账每一次扫描都能回答哪些内容被检查了、哪些被跳过、哪些失败、哪些被排除而不仅仅是输出一份 finding 列表。在 2.5.0 之前JSON 消费方CI 管道、安全编排平台面临一个经典困境一份零发现的报告到底意味着技能安全还是扫描根本没跑起来例如 LLM 分析超时、二进制文件无法解析、目录被排除——这些都会导致 finding 减少但无法从旧版报告中区分原因。2.5.0 通过顶层execution_successful状态与analysis_completeness.ledger_exceptions诊断字段让JSON 消费方可以直接阻塞不完整或失败的扫描而不是把零发现报告当作验证通过。本次版本还同步引入 V2 基线指纹格式指纹不再只是 finding 的弱哈希而是绑定扫描器版本、源内容 SHA-256 与完整 finding 证据的强指纹且带指纹的 v1 基线将被直接拒绝从根源上杜绝过期或过于宽泛的抑制。二、核心新增Inspection Ledger 执行完整性记账2.1 记账模型五种终态 × 三种记录类型Inspection Ledger 的底层契约定义在 inspection_ledger.py每个检查工作项work item都会获得一个唯一终态terminal outcome。LedgerOutcome枚举定义了五种终态终态含义completed工作项成功完成产出 findingpartial部分完成如输出达到上限被截断skipped按规则跳过如无适用文件、未启用分析器failed执行失败如 LLM 重试耗尽、分析器运行时异常out_of_scope明确声明超出扫描范围记录为 scope boundary记录类型LedgerRecordType分为三类work_item分析器对某个文件/行区间的检查工作system系统级事件如输出记录数达到上限scope_boundary范围边界记录如被排除的目录。2.2 原因白名单跳过/失败必须有理由代码与随意记录日志不同Ledger 使用白名单化的LedgerReason枚举约束所有跳过、失败、排除的原因。仓库中定义了 60 个原因码并在REASON_MESSAGES常量中为每个原因码提供安全的公开说明文案。常见类别包括文件访问类excluded_directory、hidden_file、file_disappeared、read_error、size_limit、binary_contentLLM 分析类llm_batch_failed、llm_structured_response_invalid、llm_connection_retries_exhausted归档解析类archive_malformed、archive_encrypted、archive_unsafe_member_path、archive_compression_ratio、archive_depth_limit资源边界类artifact_count_limit、traversal_depth_limit、total_bytes_limit、runtime_limit、output_limit、static_parse_limit分析器类analyzer_runtime_error、disabled_by_configuration、missing_credentials、rules_unavailable、no_applicable_files、unaccounted_work、finding_accounting_error。ledger_event()工厂函数会强制校验记账一致性inspection_ledger.pycompleted事件不允许携带 reason非completed事件必须有 reasonproducer 事件非 meta 阶段不能消费 finding校验行区间合法性start_line与end_line必须成对出现且为正整数。这意味着任何跳过或失败都必须能归因到一个明确的、可审计的原因而不是笼统地没跑。2.3 终结节点从内部事件投影出公开完整性结论finalize_inspection_ledgernodes/finalize_inspection_ledger.py是图graph中的终结节点它完成三件事补齐引用覆盖检查为被引用但未完全检查的工件生成AE1类 HIGH findingcategory 为analysis-evasion并注册对应的 reference 记账事件调用finalize_ledger()做全量对账校验每个 finding 有唯一 ID、每个 planned work 恰好有一个终态、meta 阶段 finding 传递关系正确并将检查中发现的记账错误finding_accounting_error、unaccounted_work也登记为fatalTrue的异常记录生成公开投影内部完整行保留在图状态中报告只接收 scope boundaries、跳过/失败工作、分析器摘要与安全的策略推导致命性结论——不暴露内部 work ID 与敏感载荷。finalize_ledger()产出的AnalysisCompleteness结构inspection_ledger.py包含{ total_components: 12, // 相关组件总数 scanned_components: 12, // 完全检查的组件数 coverage_percent: 100.0, // 覆盖率百分比 is_complete: true, // 是否完整 status: complete, // complete | partial | failed execution_successful: true, // 顶层执行是否成功 fully_inspected_files: 12, partially_inspected_files: 0, entirely_uninspected_files: 0, ledger_exceptions: [], // 跳过的/失败的/记账错误的公开投影 scope_exclusions: [], // 范围排除记录 analyzer_statuses: [], // 每个分析器的状态摘要 references: [], // 工件引用 limitations: [], // 限制说明 findings_before_filtering: 3, findings_after_filtering: 3 }execution_successful的判定逻辑为只要ledger_exceptions中存在任一fatalTrue的异常如failed终态、unaccounted_work、finding_accounting_error即为False。status则按失败 部分 完整三级推导有 fatal 异常为failed存在异常/限制/部分检查/未检查组件为partial否则为complete。2.4 兜底机制分析器异常不会静默吞掉为保证失败可见guard_analyzer_node()inspection_ledger.py将分析器抛出的任何未预期异常包装为安全的终态记账事实为每个组件生成failed终态事件reason 为analyzer_runtime_error附带异常类名并生成statusfailed的分析器状态事件。这样即使某个分析器崩溃扫描仍然会以失败但可诊断的方式完成报告而不是留下一个看似正常的空结果。三、输出层落地JSON 与 SARIF 的执行完整性字段3.1 JSON 输出顶层execution_successfulJSON 报告新增顶层execution_successful布尔字段与完整的analysis_completeness对象nodes/report.py。JSON 消费方现在可以按以下规则分流execution_successful: false→阻塞扫描未可靠执行不得视为验证通过存在analysis_completeness.ledger_exceptions→ 用其中reason_code、path、message、analyzers、fatal字段定位失败根因execution_successful: true但status: partial→ 有部分跳过/未检查内容需人工判断是否放行正常的 HIGH/CRITICAL finding → 继续作为普通安全策略失败处理。3.2 SARIF 输出完整性投影为通知notificationSARIF 报告将完整性信息投影为无载荷的计数与有界通知nodes/report.pyproperties.analysisCompleteness中提供isComplete、status、coveragePercent、totalComponents、fullyInspectedFiles、partiallyInspectedFiles、entirelyUninspectedFiles、ledgerExceptionCount、scopeExclusionCount、limitationCount等计数详细的 ledger 异常被渲染为 SARIF 通知error/warning/note级别并保留path、startLine/endLine位置信息同时保留可审计的抑制记录通知数量受MAX_FINDING_OUTPUT_RECORDS10,000 条上限约束超出时置notificationsTruncated: true。is_complete的判定在报告层再次收紧nodes/report.py必须同时满足status complete、execution_successful true、无部分/未检查文件、无 ledger 异常、无 limitations。3.3 终端与 Markdown 报告在 human-readable 输出中终端渲染表新增 Execution / Status / Coverage / Fully inspected / Partially inspected / Entirely uninspected 行并列出 Scope exclusions、Ledger exceptions、Analyzer statuses、Limitationsnodes/report.pyMarkdown 报告也追加等价的完整性表格。CI 校验器可以据此直接在终端或流水线日志中读到为什么被阻塞的公开完整性异常。四、行为变更递归扫描失败传播与退出码 24.1 递归扫描任一子扫描失败即整体失败2.5.0 变更了递归多技能扫描skillspector scan ./skill-collection/ --recursive的语义当任一子技能扫描失败时递归扫描整体返回失败并在合并报告中携带子扫描的状态。这消除了某个子技能实际上没扫成功但汇总报告仍显示通过的隐患。若递归技能发现本身不完整CLI 会打印警告并继续以受限范围扫描、在报告中声明 partial 覆盖cli.py。4.2 CLI 退出码语义CLI 退出码在 cli.py 中定义2.5.0 的关键变化是退出码 2致命执行/记账失败——即使 JSON 报告已经生成并写出此时execution_successful为false进程仍以退出码 2 结束让管道无法把有报告误判为通过cli.py退出码 1风险分超过阈值risk_score RISK_THRESHOLD或--fail-on-incomplete且扫描不完整退出码 0正常完成。因此JSON 集成方不能只检查进程退出码为 0还需要检查execution_successful字段反过来即使退出码为 2也应该读取已产出的 JSON 报告中的analysis_completeness.ledger_exceptions来做根因诊断——这正是 2.5.0 让报告产出与验证通过解耦的设计意图。4.3 相关 CLI 选项速查# 扫描时应用基线v2 格式 skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml # 不完整扫描即失败配合 CI skillspector scan ./my-skill/ --fail-on-incomplete --format json # 列出被基线抑制的 finding skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed # 应用技能作者随技能发布的基线默认关闭需显式开启 skillspector scan ./my-skill/ --use-shipped-baseline五、基线指纹升级V2 格式与迁移步骤5.1 V2 指纹绑定什么V2 指纹的生成逻辑在finding_fingerprint()suppression.py。与 v1 相比V2 指纹将以下维度全部纳入 SHA-256 哈希的 canonical JSON 载荷schemaskillspector-finding-fingerprint-v2_FINGERPRINT_SCHEMAscanner_version扫描器版本component组件相对路径 完整源内容UTF-8的 SHA-256 摘要finding 全量证据rule_id、severity、confidence、start_line/end_line、category、message、pattern、matched_text、finding、explanation、remediation、intent、tags、context、code_snippetsource可选identity、digest、url、depth用于 transitive传递依赖finding。任何一处源内容、扫描器版本或 finding 证据发生变化指纹都会改变从而强制要求重新审查与基线重建——这正是绑定到扫描器版本、源内容与完整 finding 证据的具体实现。V2 基线中的指纹哈希必须匹配sha256:[0-9a-f]{64}格式且每条指纹必须有非空reason含指纹的基线必须声明scanner_versionsuppression.py。V2 基线示例完整格式# SkillSpector baseline — findings listed here are suppressed on future scans. # Edit reason fields and add glob rules as needed. See docs/SUPPRESSION.md. version: 2 scanner_version: 2.5.0 rules: - id: SQP-1 reason: Trigger-phrase breadth is a description nit, not a vuln - id: SSD-2 path: *deploy-topology*/SKILL.md message: *run the exploit* reason: False positive: run the exploit is a lab test-workflow phrase fingerprints: - hash: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef rule_id: SDI-2 file: baas-build-analysis/SKILL.md reason: Accepted 2026-06-19 — first-party env detectionglob 规则沿用fnmatch语义*可跨路径分隔符匹配*SKILL.md可匹配a/b/SKILL.md**作为*的友好别名message 匹配不区分大小写建议用*keyword*包裹做子串匹配。glob 规则只作用于根扫描 findingtransitive finding 必须依赖精确指纹suppression.py。5.2 迁移步骤重新生成并人工审查2.5.0 的安全策略是拒绝带 v1 指纹的基线而不是静默容忍可能过于宽泛的抑制。升级步骤# 1. 重新扫描并生成 V2 基线默认写 .skillspector-baseline.yaml skillspector baseline ./my-skill/ # 2. 可选跳过 LLM 分析、自定义输出文件与抑制原因 skillspector baseline ./my-skill/ -o team-baseline.yaml --no-llm --reason Accepted 2026-07-24 review # 3. 人工审查生成的 V2 条目版本号、指纹、reason确认后提交替换 git diff .skillspector-baseline.yaml # 4. 后续扫描显式应用 skillspector scan ./my-skill/ --baseline .skillspector-baseline.yamlskillspector baseline命令的完整参数cli.py参数说明默认值input_path扫描路径或 URLGit URL、file URL、zip、.md 或目录必填--output/-o基线输出文件.json 扩展名输出 JSON否则输出 YAML.skillspector-baseline.yaml--no-llm仅静态分析跳过 LLMFalse--reason写入每条指纹的抑制原因Accepted finding (auto-generated baseline)--verbose/-V显示详细进度False另外需要注意skillspector baseline默认写入的.skillspector-baseline.yaml也是技能作者随技能发布基线时的唯一规范文件名SHIPPED_BASELINE_FILENAME。被发现的随包基线默认不生效只有显式传入--use-shipped-baseline才会应用cli.py防止技能作者利用基线隐藏自己技能中的问题。5.3 兼容性说明纯 rules 的 v1 基线仍然受支持但加载时会打印警告建议重新生成为 V2带 fingerprints 的 v1 基线被直接拒绝错误信息明确提示V1 指纹未绑定 finding 证据请重新扫描并用skillspector baseline重新分诊基线中scanner_version与当前扫描器版本不一致时精确指纹不会生效会有警告日志防止跨版本静默误抑制suppression.py。六、修复与加固要点2.5.0 同时修复了若干影响报告可信度的问题收紧静态分析过滤修复了文档或代码示例上下文可能宽泛抑制凭据访问类 finding 的问题——过滤判定不再因为这段代码出现在文档示例中就大范围放过credential-access类风险改进二进制与大文件处理二进制内容、超限文件现在会以binary_content、size_limit等明确的 ledger 原因记录而不是悄悄漏检加固分析器与构建上下文处理针对不安全的输入处理做了硬化同时在 SARIF 输出中保留可审计的抑制记录CI 校验器可报告公开完整性异常流水线能够直接看到解释被阻塞的ledger_exceptions而非只有退出码。以上修复均有对应测试覆盖例如 tests/nodes/test_finalize_inspection_ledger.py校验execution_successful与ledger_exceptions的推导、tests/nodes/test_analysis_completeness.py校验 JSON 与 SARIF 两种输出下的完整性投影、tests/integration/test_graph.py端到端断言coverage_percent、scope_exclusions与execution_successful。七、破坏性变更与 JSON 集成迁移指南2.5.0 对 JSON 集成方提出了明确的强制性要求详见 docs/SUPPRESSION.md 与 CHANGELOG.md将以下三种情况一律视为阻塞性验证错误输出缺失或无效进程非零失败进程退出码非零顶层execution_successful: false用analysis_completeness.ledger_exceptions做诊断向运维/安全人员展示reason_code与message继续用 HIGH/CRITICAL finding 处理普通安全策略失败——这两套信号互不替代execution_successful回答扫描本身是否可靠finding 回答内容是否安全。推荐的集成伪代码if 进程退出码 ! 0 或 输出缺失: → 阻塞构建失败 elif report.execution_successful is false: → 阻塞输出 analysis_completeness.ledger_exceptions 作为失败原因 elif report.analysis_completeness.status partial: → 告警可选按策略决定是否阻塞展示 limitations else: → 按 HIGH/CRITICAL findings 决策是否放行同时升级后必须重新生成基线运行skillspector baseline path人工审查生成的 V2 条目后提交替换带 v1 指纹的旧基线文件将无法再被加载。八、验证与版本状态2.5.0 的发布验证覆盖以下 CI 任务且全部通过lint、test-unit、test-integration、docker-smoke、sonar-scan。本版本无弃用项暂无已知限制。核心源码路径汇总如下便于继续深入阅读记账契约与终结逻辑inspection_ledger.py图节点适配nodes/finalize_inspection_ledger.py报告输出与完整性投影nodes/report.py基线指纹与抑制suppression.pyCLI 退出码与基线命令cli.py基线完整使用文档docs/SUPPRESSION.md【免费下载链接】SkillSpectorSecurity scanner for AI agent skills. Detect vulnerabilities, malicious patterns, security risks, prompt injection, data exfiltration, and supply-chain risks in Claude Code, Codex, and MCP skills before you install them.项目地址: https://gitcode.com/GitHub_Trending/sk/SkillSpector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SkillSpector 2.5.0 技术解析：Inspection Ledger 执行完整性记账与 V2 基线指纹迁移实战
SkillSpector 2.5.0 技术解析Inspection Ledger 执行完整性记账与 V2 基线指纹迁移实战【免费下载链接】SkillSpectorSecurity scanner for AI agent skills. Detect vulnerabilities, malicious patterns, security risks, prompt injection, data exfiltration, and supply-chain risks in Claude Code, Codex, and MCP skills before you install them.项目地址: https://gitcode.com/GitHub_Trending/sk/SkillSpector本篇技术指南以 SkillSpector v2.5.0 发布说明为主体深入剖析本次版本的核心能力canonical inspection-ledger规范化检查台账执行完整性报告、JSON/SARIF 输出的execution_successful状态、递归扫描失败传播、CLI 退出码 2 的语义以及必须执行的 V2 基线指纹迁移。读完本文你将掌握如何让安全自动化区分正常零发现与扫描未可靠执行并能独立完成 v1 基线的升级与 JSON 集成适配。一、版本概览为什么 2.5.0 是一次可信度升级SkillSpector 2.5.0发布于 2026-07-24引入规范化 inspection-ledger 记账每一次扫描都能回答哪些内容被检查了、哪些被跳过、哪些失败、哪些被排除而不仅仅是输出一份 finding 列表。在 2.5.0 之前JSON 消费方CI 管道、安全编排平台面临一个经典困境一份零发现的报告到底意味着技能安全还是扫描根本没跑起来例如 LLM 分析超时、二进制文件无法解析、目录被排除——这些都会导致 finding 减少但无法从旧版报告中区分原因。2.5.0 通过顶层execution_successful状态与analysis_completeness.ledger_exceptions诊断字段让JSON 消费方可以直接阻塞不完整或失败的扫描而不是把零发现报告当作验证通过。本次版本还同步引入 V2 基线指纹格式指纹不再只是 finding 的弱哈希而是绑定扫描器版本、源内容 SHA-256 与完整 finding 证据的强指纹且带指纹的 v1 基线将被直接拒绝从根源上杜绝过期或过于宽泛的抑制。二、核心新增Inspection Ledger 执行完整性记账2.1 记账模型五种终态 × 三种记录类型Inspection Ledger 的底层契约定义在 inspection_ledger.py每个检查工作项work item都会获得一个唯一终态terminal outcome。LedgerOutcome枚举定义了五种终态终态含义completed工作项成功完成产出 findingpartial部分完成如输出达到上限被截断skipped按规则跳过如无适用文件、未启用分析器failed执行失败如 LLM 重试耗尽、分析器运行时异常out_of_scope明确声明超出扫描范围记录为 scope boundary记录类型LedgerRecordType分为三类work_item分析器对某个文件/行区间的检查工作system系统级事件如输出记录数达到上限scope_boundary范围边界记录如被排除的目录。2.2 原因白名单跳过/失败必须有理由代码与随意记录日志不同Ledger 使用白名单化的LedgerReason枚举约束所有跳过、失败、排除的原因。仓库中定义了 60 个原因码并在REASON_MESSAGES常量中为每个原因码提供安全的公开说明文案。常见类别包括文件访问类excluded_directory、hidden_file、file_disappeared、read_error、size_limit、binary_contentLLM 分析类llm_batch_failed、llm_structured_response_invalid、llm_connection_retries_exhausted归档解析类archive_malformed、archive_encrypted、archive_unsafe_member_path、archive_compression_ratio、archive_depth_limit资源边界类artifact_count_limit、traversal_depth_limit、total_bytes_limit、runtime_limit、output_limit、static_parse_limit分析器类analyzer_runtime_error、disabled_by_configuration、missing_credentials、rules_unavailable、no_applicable_files、unaccounted_work、finding_accounting_error。ledger_event()工厂函数会强制校验记账一致性inspection_ledger.pycompleted事件不允许携带 reason非completed事件必须有 reasonproducer 事件非 meta 阶段不能消费 finding校验行区间合法性start_line与end_line必须成对出现且为正整数。这意味着任何跳过或失败都必须能归因到一个明确的、可审计的原因而不是笼统地没跑。2.3 终结节点从内部事件投影出公开完整性结论finalize_inspection_ledgernodes/finalize_inspection_ledger.py是图graph中的终结节点它完成三件事补齐引用覆盖检查为被引用但未完全检查的工件生成AE1类 HIGH findingcategory 为analysis-evasion并注册对应的 reference 记账事件调用finalize_ledger()做全量对账校验每个 finding 有唯一 ID、每个 planned work 恰好有一个终态、meta 阶段 finding 传递关系正确并将检查中发现的记账错误finding_accounting_error、unaccounted_work也登记为fatalTrue的异常记录生成公开投影内部完整行保留在图状态中报告只接收 scope boundaries、跳过/失败工作、分析器摘要与安全的策略推导致命性结论——不暴露内部 work ID 与敏感载荷。finalize_ledger()产出的AnalysisCompleteness结构inspection_ledger.py包含{ total_components: 12, // 相关组件总数 scanned_components: 12, // 完全检查的组件数 coverage_percent: 100.0, // 覆盖率百分比 is_complete: true, // 是否完整 status: complete, // complete | partial | failed execution_successful: true, // 顶层执行是否成功 fully_inspected_files: 12, partially_inspected_files: 0, entirely_uninspected_files: 0, ledger_exceptions: [], // 跳过的/失败的/记账错误的公开投影 scope_exclusions: [], // 范围排除记录 analyzer_statuses: [], // 每个分析器的状态摘要 references: [], // 工件引用 limitations: [], // 限制说明 findings_before_filtering: 3, findings_after_filtering: 3 }execution_successful的判定逻辑为只要ledger_exceptions中存在任一fatalTrue的异常如failed终态、unaccounted_work、finding_accounting_error即为False。status则按失败 部分 完整三级推导有 fatal 异常为failed存在异常/限制/部分检查/未检查组件为partial否则为complete。2.4 兜底机制分析器异常不会静默吞掉为保证失败可见guard_analyzer_node()inspection_ledger.py将分析器抛出的任何未预期异常包装为安全的终态记账事实为每个组件生成failed终态事件reason 为analyzer_runtime_error附带异常类名并生成statusfailed的分析器状态事件。这样即使某个分析器崩溃扫描仍然会以失败但可诊断的方式完成报告而不是留下一个看似正常的空结果。三、输出层落地JSON 与 SARIF 的执行完整性字段3.1 JSON 输出顶层execution_successfulJSON 报告新增顶层execution_successful布尔字段与完整的analysis_completeness对象nodes/report.py。JSON 消费方现在可以按以下规则分流execution_successful: false→阻塞扫描未可靠执行不得视为验证通过存在analysis_completeness.ledger_exceptions→ 用其中reason_code、path、message、analyzers、fatal字段定位失败根因execution_successful: true但status: partial→ 有部分跳过/未检查内容需人工判断是否放行正常的 HIGH/CRITICAL finding → 继续作为普通安全策略失败处理。3.2 SARIF 输出完整性投影为通知notificationSARIF 报告将完整性信息投影为无载荷的计数与有界通知nodes/report.pyproperties.analysisCompleteness中提供isComplete、status、coveragePercent、totalComponents、fullyInspectedFiles、partiallyInspectedFiles、entirelyUninspectedFiles、ledgerExceptionCount、scopeExclusionCount、limitationCount等计数详细的 ledger 异常被渲染为 SARIF 通知error/warning/note级别并保留path、startLine/endLine位置信息同时保留可审计的抑制记录通知数量受MAX_FINDING_OUTPUT_RECORDS10,000 条上限约束超出时置notificationsTruncated: true。is_complete的判定在报告层再次收紧nodes/report.py必须同时满足status complete、execution_successful true、无部分/未检查文件、无 ledger 异常、无 limitations。3.3 终端与 Markdown 报告在 human-readable 输出中终端渲染表新增 Execution / Status / Coverage / Fully inspected / Partially inspected / Entirely uninspected 行并列出 Scope exclusions、Ledger exceptions、Analyzer statuses、Limitationsnodes/report.pyMarkdown 报告也追加等价的完整性表格。CI 校验器可以据此直接在终端或流水线日志中读到为什么被阻塞的公开完整性异常。四、行为变更递归扫描失败传播与退出码 24.1 递归扫描任一子扫描失败即整体失败2.5.0 变更了递归多技能扫描skillspector scan ./skill-collection/ --recursive的语义当任一子技能扫描失败时递归扫描整体返回失败并在合并报告中携带子扫描的状态。这消除了某个子技能实际上没扫成功但汇总报告仍显示通过的隐患。若递归技能发现本身不完整CLI 会打印警告并继续以受限范围扫描、在报告中声明 partial 覆盖cli.py。4.2 CLI 退出码语义CLI 退出码在 cli.py 中定义2.5.0 的关键变化是退出码 2致命执行/记账失败——即使 JSON 报告已经生成并写出此时execution_successful为false进程仍以退出码 2 结束让管道无法把有报告误判为通过cli.py退出码 1风险分超过阈值risk_score RISK_THRESHOLD或--fail-on-incomplete且扫描不完整退出码 0正常完成。因此JSON 集成方不能只检查进程退出码为 0还需要检查execution_successful字段反过来即使退出码为 2也应该读取已产出的 JSON 报告中的analysis_completeness.ledger_exceptions来做根因诊断——这正是 2.5.0 让报告产出与验证通过解耦的设计意图。4.3 相关 CLI 选项速查# 扫描时应用基线v2 格式 skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml # 不完整扫描即失败配合 CI skillspector scan ./my-skill/ --fail-on-incomplete --format json # 列出被基线抑制的 finding skillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed # 应用技能作者随技能发布的基线默认关闭需显式开启 skillspector scan ./my-skill/ --use-shipped-baseline五、基线指纹升级V2 格式与迁移步骤5.1 V2 指纹绑定什么V2 指纹的生成逻辑在finding_fingerprint()suppression.py。与 v1 相比V2 指纹将以下维度全部纳入 SHA-256 哈希的 canonical JSON 载荷schemaskillspector-finding-fingerprint-v2_FINGERPRINT_SCHEMAscanner_version扫描器版本component组件相对路径 完整源内容UTF-8的 SHA-256 摘要finding 全量证据rule_id、severity、confidence、start_line/end_line、category、message、pattern、matched_text、finding、explanation、remediation、intent、tags、context、code_snippetsource可选identity、digest、url、depth用于 transitive传递依赖finding。任何一处源内容、扫描器版本或 finding 证据发生变化指纹都会改变从而强制要求重新审查与基线重建——这正是绑定到扫描器版本、源内容与完整 finding 证据的具体实现。V2 基线中的指纹哈希必须匹配sha256:[0-9a-f]{64}格式且每条指纹必须有非空reason含指纹的基线必须声明scanner_versionsuppression.py。V2 基线示例完整格式# SkillSpector baseline — findings listed here are suppressed on future scans. # Edit reason fields and add glob rules as needed. See docs/SUPPRESSION.md. version: 2 scanner_version: 2.5.0 rules: - id: SQP-1 reason: Trigger-phrase breadth is a description nit, not a vuln - id: SSD-2 path: *deploy-topology*/SKILL.md message: *run the exploit* reason: False positive: run the exploit is a lab test-workflow phrase fingerprints: - hash: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef rule_id: SDI-2 file: baas-build-analysis/SKILL.md reason: Accepted 2026-06-19 — first-party env detectionglob 规则沿用fnmatch语义*可跨路径分隔符匹配*SKILL.md可匹配a/b/SKILL.md**作为*的友好别名message 匹配不区分大小写建议用*keyword*包裹做子串匹配。glob 规则只作用于根扫描 findingtransitive finding 必须依赖精确指纹suppression.py。5.2 迁移步骤重新生成并人工审查2.5.0 的安全策略是拒绝带 v1 指纹的基线而不是静默容忍可能过于宽泛的抑制。升级步骤# 1. 重新扫描并生成 V2 基线默认写 .skillspector-baseline.yaml skillspector baseline ./my-skill/ # 2. 可选跳过 LLM 分析、自定义输出文件与抑制原因 skillspector baseline ./my-skill/ -o team-baseline.yaml --no-llm --reason Accepted 2026-07-24 review # 3. 人工审查生成的 V2 条目版本号、指纹、reason确认后提交替换 git diff .skillspector-baseline.yaml # 4. 后续扫描显式应用 skillspector scan ./my-skill/ --baseline .skillspector-baseline.yamlskillspector baseline命令的完整参数cli.py参数说明默认值input_path扫描路径或 URLGit URL、file URL、zip、.md 或目录必填--output/-o基线输出文件.json 扩展名输出 JSON否则输出 YAML.skillspector-baseline.yaml--no-llm仅静态分析跳过 LLMFalse--reason写入每条指纹的抑制原因Accepted finding (auto-generated baseline)--verbose/-V显示详细进度False另外需要注意skillspector baseline默认写入的.skillspector-baseline.yaml也是技能作者随技能发布基线时的唯一规范文件名SHIPPED_BASELINE_FILENAME。被发现的随包基线默认不生效只有显式传入--use-shipped-baseline才会应用cli.py防止技能作者利用基线隐藏自己技能中的问题。5.3 兼容性说明纯 rules 的 v1 基线仍然受支持但加载时会打印警告建议重新生成为 V2带 fingerprints 的 v1 基线被直接拒绝错误信息明确提示V1 指纹未绑定 finding 证据请重新扫描并用skillspector baseline重新分诊基线中scanner_version与当前扫描器版本不一致时精确指纹不会生效会有警告日志防止跨版本静默误抑制suppression.py。六、修复与加固要点2.5.0 同时修复了若干影响报告可信度的问题收紧静态分析过滤修复了文档或代码示例上下文可能宽泛抑制凭据访问类 finding 的问题——过滤判定不再因为这段代码出现在文档示例中就大范围放过credential-access类风险改进二进制与大文件处理二进制内容、超限文件现在会以binary_content、size_limit等明确的 ledger 原因记录而不是悄悄漏检加固分析器与构建上下文处理针对不安全的输入处理做了硬化同时在 SARIF 输出中保留可审计的抑制记录CI 校验器可报告公开完整性异常流水线能够直接看到解释被阻塞的ledger_exceptions而非只有退出码。以上修复均有对应测试覆盖例如 tests/nodes/test_finalize_inspection_ledger.py校验execution_successful与ledger_exceptions的推导、tests/nodes/test_analysis_completeness.py校验 JSON 与 SARIF 两种输出下的完整性投影、tests/integration/test_graph.py端到端断言coverage_percent、scope_exclusions与execution_successful。七、破坏性变更与 JSON 集成迁移指南2.5.0 对 JSON 集成方提出了明确的强制性要求详见 docs/SUPPRESSION.md 与 CHANGELOG.md将以下三种情况一律视为阻塞性验证错误输出缺失或无效进程非零失败进程退出码非零顶层execution_successful: false用analysis_completeness.ledger_exceptions做诊断向运维/安全人员展示reason_code与message继续用 HIGH/CRITICAL finding 处理普通安全策略失败——这两套信号互不替代execution_successful回答扫描本身是否可靠finding 回答内容是否安全。推荐的集成伪代码if 进程退出码 ! 0 或 输出缺失: → 阻塞构建失败 elif report.execution_successful is false: → 阻塞输出 analysis_completeness.ledger_exceptions 作为失败原因 elif report.analysis_completeness.status partial: → 告警可选按策略决定是否阻塞展示 limitations else: → 按 HIGH/CRITICAL findings 决策是否放行同时升级后必须重新生成基线运行skillspector baseline path人工审查生成的 V2 条目后提交替换带 v1 指纹的旧基线文件将无法再被加载。八、验证与版本状态2.5.0 的发布验证覆盖以下 CI 任务且全部通过lint、test-unit、test-integration、docker-smoke、sonar-scan。本版本无弃用项暂无已知限制。核心源码路径汇总如下便于继续深入阅读记账契约与终结逻辑inspection_ledger.py图节点适配nodes/finalize_inspection_ledger.py报告输出与完整性投影nodes/report.py基线指纹与抑制suppression.pyCLI 退出码与基线命令cli.py基线完整使用文档docs/SUPPRESSION.md【免费下载链接】SkillSpectorSecurity scanner for AI agent skills. Detect vulnerabilities, malicious patterns, security risks, prompt injection, data exfiltration, and supply-chain risks in Claude Code, Codex, and MCP skills before you install them.项目地址: https://gitcode.com/GitHub_Trending/sk/SkillSpector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考