ch040602/skill-vaccine

# Skill Vaccine **在 Agent Skill 到达 Codex、Claude Code、CI 或 registry 之前，为其提供扫描门禁安全保护。**

`agent-skills` · `skill-security` · `prompt-injection` · `supply-chain-security` · `sarif` · `codex` · `claude-code` Skill Vaccine 是用于 Agent Skill 包的本地扫描门禁。它将一个确定性 CLI， `skill-vaccine`，与一个可选的 Agent Skill 适配器 `skills/skill-vaccine-review` 结合在一起，使团队能够 在 CI 中拦截高风险包，通过结构化证据审查第三方 skill，并且仅在扫描裁决通过后进行安装。 ## 目录 - [为什么](#why) - [这是什么](#what-this-is) - [安装](#install) - [npm 包管理](#npm-package-management) - [快速开始](#quick-start) - [输出](#outputs) - [审查后安装](#review-then-install) - [Agent 辅助审查](#agent-assisted-review) - [策略配置](#policy-profiles) - [集成](#integrations) - [文档](#documentation) - [研究基础](#research-basis) - [贡献](#contributing) - [开发](#development) ## 为什么 Agent skill 可能会在自然语言指令、权限声明、辅助脚本和 registry 元数据中隐藏风险。Skill Vaccine 提供了一个本地静态审查层，包含可选的 语义路由合约、准入裁决、信任等级元数据、SARIF 输出和 benchmark 测试固定数据。 当前的检查涵盖： - prompt injection、机密窃取、隐藏行为和绕过治理 - `SKILL.md` 中过于宽泛的发现或选择措辞 - 在 Python、shell、 PowerShell、batch 和 JavaScript 固定数据测试集中，`SKILL.md`、引用的 Markdown 文档和辅助脚本里的高风险行为 - 缺失或不匹配的权限/能力声明 - registry 元数据来源缺失 - 跨文件隐藏能力及跨 skill 风险图谱链接 - 语义审查覆盖缺口及厂商中立的 Layer 2 / Layer 3 合约 ## 这是什么 Skill Vaccine 是一个具有两个入口点的单一产品： | 入口点 | 用途 | | --- | --- | | `skill-vaccine` CLI | 确定性本地扫描、CI 门禁、SARIF 输出、manifest、benchmark 检查和证据包生成。 | | `skills/skill-vaccine-review` | Codex/Claude Code 适配器，要求宿主 agent 审查由 CLI 生成的安全数据包。 | 该适配器并不取代 CLI。它封装 CLI 证据用于语义审查，并确保 受审查的 skill 代码不被执行。 ## 安装 在包发布后从 npm 获取： ``` npm install -g @cchsh/skill-vaccine skill-vaccine --help ``` 从检出版本构建： ``` python -m pip install -e . skill-vaccine --help ``` 或直接通过内置的 Node 包装器从源码树运行： ``` node bin\skill-vaccine.js scan tests\fixtures\benign_skill ``` 对于本地 Codex 使用，请通过将安装的 skill 链接到此检出版本来保持单一事实来源： ``` New-Item -ItemType Junction ` -Path "$env:USERPROFILE\.codex\skills\skill-vaccine-review" ` -Target ".\skills\skill-vaccine-review" ``` 除非你有意让它与提交并推送的版本产生差异，否则不要维护单独的 skill 文件夹副本。 ## npm 包管理 npm 包标识为 `@cchsh/skill-vaccine`，它通过 `bin/skill-vaccine.js` 暴露 `skill-vaccine` 二进制文件。该包配置为公开作用域发布，包含 `publishConfig.access = public`。 于 2026-06-26 检查的 registry 状态： - `npm view @cchsh/skill-vaccine ...` 返回 `404 Not Found`，因此该包名尚未 在 npm 上发布。 - `npm whoami` 返回 `E401`，因此此工作站当前未通过 npm 认证。 - `npm pack --dry-run` 通过测试，并包含 CLI 包装器、Python 包、文档、研究摘要 以及 `skills/skill-vaccine-review`。 发布前： ``` npm login npm whoami npm pack --dry-run npm publish --access public npm view @cchsh/skill-vaccine name version repository.url homepage --json ``` 在 npm 包发布之前，请使用 `python -m pip install -e .` 从检出版本安装，或者 使用 `node bin\skill-vaccine.js ...` 直接运行内置的包装器。 ## 快速开始 扫描一个 skill： ``` skill-vaccine scan path\to\skill --format text skill-vaccine scan path\to\skill --format json skill-vaccine scan path\to\skill --format sarif --fail-on high ``` 仅在通过安装门禁时，扫描并将一个本地 Agent Skill 包安装到 Codex： ``` skill-vaccine install path\to\skill --format json skill-vaccine install path\to\skill --skills-dir "$env:USERPROFILE\.codex\skills" --format json ``` 使用 JSON 或 TOML 配置： ``` skill-vaccine scan path\to\skill --config skill-vaccine.json --format json skill-vaccine scan path\to\skill --config skill-vaccine.toml --format json ``` 检查相关的合约和报告： ``` skill-vaccine manifest suggest path\to\skill skill-vaccine semantic schema skill-vaccine semantic review path\to\skill --provider fake skill-vaccine jury schema skill-vaccine jury review path\to\skill --provider fake skill-vaccine llm schema skill-vaccine llm prompt path\to\skill --target codex --format markdown skill-vaccine llm validate llm-response.json skill-vaccine graph path\to\skills skill-vaccine eval tests\fixtures\benchmark\labels.json skill-vaccine telemetry schema skill-vaccine trust profiles skill-vaccine trust host-profiles ``` ## 输出 每次扫描都会报告： - `max_severity`：最高的活动发现严重级别 - `verdict`：`approved`、`conditional` 或 `rejected` - `required_trust_tier`：`unvetted`、`local-only`、`reviewed` 或 `trusted` - `inferred_capabilities`：从发现和声明中推导出的能力 ID - `findings`：规则 ID、证据、能力 ID、生命周期阶段和抑制元数据 JSON 和 SARIF 旨在用于 CI、registry 接入和审查自动化。文本输出用于本地 筛选。 ## 审查后安装 `skill-vaccine install` 是用于安装另一个 Agent Skill 的本地安装路径。它会扫描 恰好一个本地 skill 包，从 `SKILL.md` frontmatter 中读取 skill 名称，并且只有在 扫描结果低于安装阈值时才将其复制到 Codex skills 目录中。默认阈值为 `high`，因此 `high` 和 `critical` 发现会阻止安装。 CLI 路径： ``` # 1. 检查候选 skill 而不安装它。 skill-vaccine scan path\to\candidate-skill --format text # 2. 仅在 scan gate 通过时安装。 skill-vaccine install path\to\candidate-skill --format json # 3. 在需要时使用更严格的本地 policy。 skill-vaccine install path\to\candidate-skill --fail-on medium ``` 显式 Codex skills 目录： ``` skill-vaccine install path\to\candidate-skill ` --skills-dir "$env:USERPROFILE\.codex\skills" ` --format json ``` Agent Skill 路径： ``` Use $skill-vaccine-review to review path\to\candidate-skill and install it only if it passes. ``` 适配器首先要求 CLI 使用 `skill-vaccine llm prompt ...` 创建一个安全的证据包。语义审查后，它使用 `skill-vaccine install ...` 进行 实际安装。agent 不应手动从 候选 skill 中复制、链接、执行或运行安装脚本。 install 命令不会获取远程仓库、执行受审查的脚本、运行包 安装器或覆盖已安装的现有 skill。被阻止的结果会返回 `blocked: true`、 `installed: false`，并确保候选 skill 不会进入 Codex skills 目录。 ## Agent 辅助审查 Skill Vaccine 有两种显式模式。 | 模式 | 适用场景 | 执行内容 | LLM 行为 | | --- | --- | --- | --- | | 纯 CLI 模式 | 您需要确定性本地扫描、安装门禁、CI 门禁、SARIF、benchmark 或 registry 接入。 | `skill-vaccine scan`、`skill-vaccine install`、`semantic review --provider fake`、`jury review --provider fake`。 | 不调用 LLM。无网络。不执行受审查的 skill 代码。 | | Agent 辅助审查 | 您希望 Codex 或 Claude Code 判断意图、权限合理性、隐蔽行为、跨文件一致性，或是否应该安装受审查的 skill。 | `skills/skill-vaccine-review` 运行 `skill-vaccine llm prompt ...`；为了安装，它会在审查后运行 `skill-vaccine install ...`。 | 宿主 agent LLM 在会话中审查数据包。CLI 本身仍然不会调用模型 API。 | 直接生成审查数据包： ``` skill-vaccine llm schema skill-vaccine llm prompt path\to\skill --target codex --format markdown skill-vaccine llm prompt path\to\skill --target claude-code --format json skill-vaccine llm validate llm-response.json ``` `skill-vaccine llm schema` 打印 prompt 数据包和预期 LLM 响应的 JSON 合约。`skill-vaccine llm prompt` 在每个 JSON 数据包中嵌入相同的 `response_schema`，并在 Markdown 输出中打印它，以便 Codex 或 Claude Code 可以返回机器可检查的审查结果。 `skill-vaccine llm validate` 根据该合约检查保存的 LLM 响应产物，并在 必填字段、枚举值、分数范围或数组字段无效时以非零状态退出。 从此仓库使用可安装的 Agent Skill 适配器： ``` skills/skill-vaccine-review ``` 该适配器特意保持很小：它告知 Codex 或 Claude Code 收集本地静态证据， 避免执行受审查的 skill 代码，保留关键的静态发现，并返回结构化的 包含语义任务结果的 JSON。这就是分层模式：首先进行快速的静态筛选，仅在需要判断时才进行 语义审查。 ## 策略配置 信任等级描述了 skill 所需的最小操作者边界。宿主配置文件为特定 环境选择默认扫描设置。 内置的宿主配置文件： | 配置文件 | 默认阈值 | 额外检查 | 适用场景 | | --- | --- | --- | --- | | `local` | `critical` | 无 | 开发者工作站筛选 | | `ci` | `high` | 无 | 拉取请求和构建门禁 | | `registry` | `medium` | 语义路由、元数据审计 | registry 接入 | | `marketplace-review` | `low` | 语义路由、元数据审计 | 严格的市场审查 | 显式的 CLI 标志会覆盖配置值；配置值会覆盖宿主配置文件的默认值。 ## 集成 GitHub Actions： ``` - uses: ./ with: path: . fail-on: critical sarif-file: skill-vaccine-review.sarif ``` pre-commit： ``` repos: - repo: local hooks: - id: skill-vaccine-review name: Skill Vaccine entry: skill-vaccine scan . language: python pass_filenames: false args: [--fail-on, high] ``` ## 文档 - [规则](docs/rules.md) - [能力](docs/capabilities.md) - [配置](docs/config.md) - [宿主配置文件](docs/host-profiles.md) - [信任等级](docs/trust-tiers.md) - [裁决](docs/verdicts.md) - [抑制](docs/suppressions.md) - [Registry 生命周期风险](docs/registry-lifecycle-risks.md) - [跨文件一致性](docs/cross-file-consistency.md) - [风险图谱](docs/risk-graph.md) - [元数据审计](docs/metadata-audit.md) - [语义 Layer 2](docs/semantic-layer2.md) - [陪审 Layer 3](docs/jury-layer3.md) - [Telemetry schema](docs/telemetry.md) - [Benchmark](docs/benchmark.md) - [GitHub Action](docs/github-action.md) - [pre-commit](docs/pre-commit.md) - [发布](docs/release.md) - [贡献](CONTRIBUTING.md) ## 研究基础 Skill Vaccine 基于以下链接的本地研究综合： [research/skill-vaccine-research-synthesis.md](research/skill-vaccine-research-synthesis.md)。韩语 论文摘要索引在 [research/paper_summaries/index.md](research/paper_summaries/index.md)。 该实现将来自 SkillSieve、SkillGuard、SkillProbe、Skilldex、OpenSkillEval、 SkillsBench、EvoSkills、SKILL.md 语义攻击工作以及更广泛的 agent-skill 领域论文的思想映射为 静态规则、语义路由合约、jury 协议脚手架、评估固定数据集以及 准入策略元数据。 ## 开发 运行测试： ``` python -m pytest python -m compileall -q src tests ``` 构建分发制品： ``` python -m pip wheel . --no-deps --no-build-isolation -w .codex\review-driven-development\artifacts\wheel-smoke npm pack --dry-run ``` 在内置固定数据集上的当前 benchmark 冒烟测试指标： - cases：`14` - benign controls：`2` - risky cases：`12` - precision：`1.0` - recall：`1.0` - F1：`1.0` - F2：`1.0` - FPR：`0.0` - suspicious rate：`0.8571` - escalation rate：`0.7143` - rule coverage：`1.0` 这些是针对 MVP 固定数据集的合约冒烟测试指标，并非广泛的扫描器质量声明。

标签：AI智能体安全, DNS 反向解析, MITM代理, Python安全, 提示词注入防御, 暗色界面, 逆向工具, 零日漏洞检测, 静态代码扫描