VladimirPutkov/auditskill

# AuditSkill **一个零鉴权的 HTTP API，帮助 agent 在任何内容进入 context window 之前，找到、验证并安全地加载正确的 skill。** NANDA 解决了发现问题。AuditSkill 解决了下一个问题：**“这些 skill 中我到底应该使用哪一个——它安全吗，值得付出这个成本吗？”** 查找 → 验证 → 加载。只需一次 POST 请求。即可获得一个确定性判定、按模型计算的成本预估、排名后的注册表，以及任何 agent 都可以离线验证的签名证书。 它是一个**预加载文档审计器**。身份注册表证明 agent 是谁；runtime 防火墙限制 agent 做什么；支付和信誉层跟踪交易。它们都没有在 agent 读取 skill *文档*之前对其进行检查——而这正是恶意的 SKILL.md 造成破坏的关键时刻。AuditSkill 填补了这一空白，并与这三层架构互为补充。 ## 问题所在 在 Open Agentic Web 中，Agent 会在 runtime 发现 skill 并将其作为 context 加载。skill 文件成为了 agent 指令集的一部分。这造成了两种攻击面，无论多少 agent 端的防护措施都无法完全消除： ### 1. Skill 文件是一种注入向量 [OWASP 将 Prompt Injection 评为](https://owasp.org/www-project-top-10-for-large-language-model-applications/)（LLM01）其 2025 年 LLM 应用程序十大安全漏洞的**第一名**（#1 vulnerability）。根本原因在于结构性问题：一旦指令和数据都占据了 context window，LLM 就无法区分它们。 Skill 文件尤其危险，因为它们在设计上*本身就是*指令。一个恶意的 SKILL.md 可以嵌入： - **Prompt injection** — “忽略之前的指令”覆盖、角色重分配、context 重置 - **隐藏指令** — 零宽 Unicode 字符（U+200B、U+FEFF）、双向覆盖（U+202E）、带有祈使动词的 HTML 注释、代码块之外的超长 Base64 数据块 - **数据泄露** — 将环境变量、API key 或对话 context POST 到攻击者控制的 URL 的 endpoint - **危险操作** — `rm -rf`、`DROP TABLE`、`eval()`、通过 `sudo` 或 `chmod 777` 进行特权提升 [Snyk ToxicSkills 报告](https://snyk.io/blog/toxicskills-malicious-ai-agent-skills-clawhub/)（2026 年 2 月）扫描了来自公共注册表（ClawHub、skills.sh）的 3,984 个 skill。**36.82%（1,467 个 skill）至少有一个安全缺陷**，13.4%（534 个）至少有一个严重问题，并且有 76 个被人工确认为恶意 — 其中 91% 将恶意软件模式与 prompt injection 结合在一起。真实的事件证实了这一威胁：[EchoLeak (CVE-2025-32711)](https://arxiv.org/abs/2509.10540)，CVSS 9.3，演示了通过共享文档中的隐藏指令从 Microsoft 365 Copilot 进行零点击数据泄露 — 其 payload 是一个对用户不可见的 HTML 注释。 这些并非理论上的。[SKILL-INJECT 基准测试](https://arxiv.org/abs/2602.20156)精确测量了这类攻击 — 通过 skill 文件进行的“指令中注入”攻击 — 包含跨越数据泄露、破坏性操作、勒索软件和后门的 202 个注入-任务对。 ### 2. 臃肿的 skill 文件浪费了 context window skill 文件消耗的每一个 token，都是 agent 无法用于实际任务的 token。在当今的 NANDA Town 实时注册表中，经过审计的 skill 文件大小从 ~100 到 ~3,700 个 token 不等，并且至少有一个列表的源文档高达 295 KB — 根本无法安全加载。一个在开始工作前加载了三个冗长 skill 的 agent 很容易仅在这些指令上就消耗 10,000+ 个 token，而对于小 context window 模型来说，这在其拥有的全部资源中占据了相当大的比例。 目前没有任何现有服务能够在 agent 运行时（即文件进入 context window 之前）同时回答这两个问题 — *这个文件安全吗？* 以及 *这个文件值得阅读吗？* ## AuditSkill 的工作原理 AuditSkill 是一个确定性的、基于规则的 pipeline。**不使用 LLM。** Agent 发送一个 SKILL.md（原始文本或 URL）。服务返回判定结果、各模块得分、发现列表、context 成本预估，以及一个 Ed25519 签名的证书。 ``` flowchart LR A["Agent discovers
a SKILL.md"] --> B["POST /audit"] B --> C["Parse"] C --> D["Security scan
34 rules"] C --> E["Structure
scoring"] C --> F["Scope
analysis"] C --> G["Metadata
check"] C --> H["Liveness
GET/HEAD probes"] D & E & F & G & H --> I["Score aggregation
& verdict"] I --> J["Ed25519 sign
certificate"] J --> K["Return verdict +
signed certificate"] ``` ### 安全审计 — 34 条规则，8 个类别 | 类别 | 规则 | 严重性 | 捕获内容 | |---|---|---|---| | Prompt injection | SEC-001 – SEC-005 | 严重 | “忽略之前的指令”、角色劫持、context 重置、绕过安全限制 | | 数据泄露 | SEC-006 – SEC-010, SEC-034 | 严重 / 高危 | 向外部 URL POST 密钥、带有 token 的 curl、回传模式、文件中硬编码的活跃提供商密钥 | | 不安全的操作 | SEC-011 – SEC-015 | 高危 | `rm -rf`、`DROP TABLE`、`eval()`、`sudo`、磁盘格式化命令 | | 隐藏指令 | SEC-016 – SEC-020 | 高危 | 零宽字符、双向覆盖、Base64 数据块、带有祈使语气的 HTML 注释、IDN 同形异义字 | | 范围蔓延 | SEC-021 – SEC-025 | 中危 | “无限制权限”、“完全控制”、绕过身份验证、无限制的范围声明 | | 供应链 | SEC-026 – SEC-027 | 严重 | 从远程 URL/tarball 安装包、通过管道传输到 shell 的引导脚本 | | Agent 捕获 | SEC-028 – SEC-030 | 高危/中危 | 重写代理变量以重新路由所有 agent 流量、分离的后台 daemon、强制通过单一外部服务进行 gating | | 支付安全 | SEC-031 – SEC-033 | 严重 / 高危 / 中危 | 凭据移交（将 agent 自己的 LLM 提供商 API key 发送给 skill）、没有支出上限的自动充值、无限的支付重试循环 | 供应链、Agent 捕获和支付安全类别源于对 NANDA Town 实时注册表中已部署 skill 的审计。其中一个“安全层” skill 指示 agent 从其自己的服务器安装 tarball，通过其代理重新路由所有流量，保持后台 daemon 运行，并在其 endpoint 无法访问时停止所有工作。另一个注册表 skill 要求 agent 将自己的 OpenAI/Anthropic key POST 到 `set-api-key` endpoint。这些指令中的每一条现在都成为一个独立的、带有行号的发现。 域名一致性检查还会标记任何声明为 `METHOD https://…` 且其主机与 skill 自身 Base URL 不同的 endpoint — 这是一种未记录目的地的信号，且不会干扰正文中的链接。 防误报机制：代码块和描述性部分（“限制”、“检测模式”）内的模式会被排除，因此合法的安全工具不会被标记。否定陈述（“此 skill **不会**覆盖您的系统指令”）被明确排除在 prompt injection 规则之外。这已通过 `benign_security_skill` 和 `supply_chain_skill` 固件进行了回归测试。 ### Context 卫生 每次审计都包含一个带有**按模型**细分的 `context_cost` 对象： ``` { "tokens_estimate": 4200, "size_bytes": 16800, "density": "low", "per_model": [ { "model": "claude-haiku-4-5", "tokens": 4421, "input_cost_usd": 0.004421, "window_pct": 2.21 }, { "model": "gemini-3", "tokens": 4000, "input_cost_usd": 0.056, "window_pct": 0.4 } ], "error_margin_pct": 10, "price_source": "AuditSkill built-in price table (as_of 2026-07-04)", "recommendation": "This skill file is 4,200 tokens — larger than the ~1,500 token median. Information density is low." } ``` 密度根据有用信号（endpoint、示例、已记录的部分）与总 token 的比率被分类为 `high`、`medium` 或 `low`。超过 3,000 个 token 且密度较低的文件将被明确标记。 **价格是自包含的。** 美元数字和 context window 大小来自 AuditSkill 内置于服务中维护的价格表 — 不依赖任何第三方 skill 或外部数据源。安全审计器绝不能信任未经验证的外部来源来提供其所报告的数字，因此该表是唯一的真实来源；`price_source` 记录了其生效日期。因此，预估严格保持离线和确定性。Token 计数针对每个模型系列（每 token 的字符数）进行校准，并诚实地标明 `error_margin_pct` — 这足以做出加载/跳过决策，且无需依赖重型 tokenizer，也不需要任何密钥。向 `/audit` 传递 `model` 可将范围缩小到您的模型；对于相同的文件，答案是逐字节相同的。 ### 排名发现 — 决策引擎 `GET /discover` 不仅仅是列出带有判定结果的注册表 — 它会返回**最好优先**的结果。每个条目都会获得一个 `rank` 和一个纯语言的 `rank_reason`。通过的 skill 领先，按已发布的综合得分排序（`overall_score` + 密度奖励：高/中/低分别为 `+5 / 0 / -5`），并采用确定性的平局打破规则（先看得分，然后是较少的严重发现，最后是名称）；未通过的 skill 紧随其后；无法审计的条目排在最后并附带原因。该公式在 `/benchmarks` 上原样公开 — 没有任何隐藏的魔法。这就是核心任务在一次调用中的体现：不是“这里是现有的东西”，而是“这里是安全可加载的 skill，以及原因”。 ### 判定结果 | 判定 | 条件 | Agent 操作 | |---|---|---| | `PASS_BASIC_AUDIT` | 得分 ≥ 85，无中危及以上发现 | 可安全使用 | | `PASS_WITH_WARNINGS` | 得分 ≥ 70，无高危/严重发现 | 谨慎使用 | | `REQUIRES_HUMAN_REVIEW` | 得分 ≥ 40，或存在任何高危发现 | 升级交由人工处理 | | `FAILS_BASIC_AUDIT` | 得分 < 40，或存在任何严重发现 | 请勿使用 | 评分权重：`structure 0.30 · security 0.30 · liveness 0.25 · metadata 0.10 · scope 0.05`。权重会根据实际运行的模块进行重新归一化 — 缺失的模块绝不会无声无息地扣除分数。 ### 签名证书 每个判定结果都会被打包为 Ed25519 签名的证书。任何 agent 都可以对其进行验证： - **在线**：将证书 POST 到 `/verify` - **离线**：使用 `/.well-known/auditskill-keys` 中的公钥检查签名 无需回调 AuditSkill。该证书是可移植且无状态的。 ## API 概览 — 9 个 Endpoint，零鉴权 | 方法 | 路径 | 用途 | |---|---|---| | `POST` | `/audit` | 对 SKILL.md 进行全面审计。接受 `skill_md`（原始文本）或 `skill_url`（HTTPS）。返回判定结果 + 签名证书。 | | `POST` | `/verify` | 对证书进行无状态的 Ed25519 签名验证。 | | `GET` | `/discover` | 对实时的 NANDA Town 注册表进行内联审计。返回附带判定结果的列表。 | | `GET` | `/certificate/{id}` | 通过 ID 获取存储的证书。 | | `GET` | `/certificates?skill_hash=…` | 信任注册表查找 — “这个确切的 skill 以前被审计过吗？” | | `GET` | `/.well-known/auditskill-keys` | 用于离线证书验证的公钥。 | | `GET` | `/health` | 存活探针。 | | `GET` | `/about` | 机器可读的清单 — 用途、解决的两个问题、服务对象、使用时机。 | | `GET` | `/benchmarks` | 评分权重、阈值和规则类别（完全透明）。 | ## 快速开始 ``` # 1. 检查服务是否已启动 curl https://auditskill.up.railway.app/health # 2. 审计 skill 文件（静态模式 — 无网络探测） curl -X POST https://auditskill.up.railway.app/audit \ -H "Content-Type: application/json" \ -d '{"skill_md": "# Weather\n\nGet weather.\n\n## Base URL\nhttps://api.example.com\n\n## Endpoints\nGET /weather?city={city}", "mode": "safe_static"}' # 3. 通过 URL 从 NANDA Town registry 审计 skill（带 liveness 探针） curl -X POST https://auditskill.up.railway.app/audit \ -H "Content-Type: application/json" \ -d '{"skill_url": "https://raw.githubusercontent.com/user/repo/main/SKILL.md", "mode": "liveness"}' ``` ## 安全态势 这是一个安全产品。其自身的攻击面已得到强化： - **防 SSRF 的出站请求。** 每次探测都会通过防 DNS 重绑定保护：协议白名单、主机名黑名单（`localhost`、`*.internal`、`metadata.google.internal`）、IP 段封锁（环回地址、RFC 1918、链路本地地址 169.254/16、云元数据、CGNAT 100.64/10、0.0.0.0/8、IPv6 等效地址、十进制编码的环回地址）。解析出的 IP 会在连接期间被固定，同时 TLS SNI/证书验证始终绑定到真实的主机名。 - **只读探测。** 存活检查仅发送 GET/HEAD。绝不执行 PUT/POST/PATCH/DELETE。 - **滥用控制。** 每次审计的 endpoint 数量 ≤15，单域名上限，单请求 3 秒超时，全局约 25 秒超时，200 KB 输入上限，`skill_url` 强制使用 HTTPS，单 IP 速率限制，skill 哈希结果缓存。 - **无误报自我毒化** 服务会审计自身的 SKILL.md 并将其认证为 `PASS_BASIC_AUDIT` — 审计器在自己身上“吃狗粮”（测试自身产品），却不会对其所记录的安全术语进行误报标记。 ## 在本地运行 ``` pip install -e . python scripts/generate_keys.py # prints AUDITSKILL_PRIVATE_KEY / _PUBLIC_KEY / _KEY_ID export AUDITSKILL_PRIVATE_KEY=... # paste from output export AUDITSKILL_PUBLIC_KEY=... export AUDITSKILL_KEY_ID=... uvicorn auditskill.api.main:app --reload --port 8000 ``` ## 测试 ``` pip install -e ".[dev]" pytest -q ``` 测试套件涵盖：SSRF 阻断（包括十进制编码的环回地址和云元数据目标）、分数重新归一化、判定边界、带有篡改检测的 Ed25519 签名往返测试、针对合法的安全**和支付** skill 的误报防护、每条易误报规则的阴性样本（否定的“不会覆盖”措辞、从 index 进行的普通 `pip install`、有上限的自动支付、`X-Api-Key` 身份验证文档、占位符 `sk-...`）、规避抵抗（零宽拼接和同形异义字伪装的注入、短小的 Base64 走私 payload）、按模型计算的成本估算器（未知模型拒绝、单一模型范围缩放）、确定性的 `/discover` 排名、URL 发现去重、方法不匹配崩溃回归、skill 名称清理、非 skill/空文档拒绝、纯 Markdown 解析，以及对正常/恶意/良性/损坏/供应链/**支付陷阱**固件的端到端判定测试。 ## 局限性 基于规则且具有确定性。AuditSkill 会标记已知的危险模式并测试可达性；它不证明语义正确性或未来的安全性。`PASS` 意味着“未发现危险信号”，而不是一种保证。存活检查是时间点的检查，从不执行写入 endpoint。Context 成本估算使用基于字符的 token 启发式方法（粗略估计为 ÷4；在 `per_model` 中针对每个模型系列校准每 token 的字符数），而不是真实的 tokenizer — 诚实的误差范围是 `error_margin_pct`（~10%）。 ## License MIT

标签：API服务, DNS 反向解析, Homebrew安装, Python脚本, 上下文审计, 大模型安全, 提示词注入检测, 零信任架构