RECTOR-LABS/solana-cpi-safety-skill

# solana-cpi-safety-skill 适用于 Claude Code 的 Solana CPI 安全技能 —— 检测并防范四类跨程序调用漏洞，并提供对 CPI return-data 伪造的顶级覆盖。 ## 这是什么 跨程序调用 (CPI) 是 Solana 上严重且可被利用的漏洞的最常见来源。本技能旨在教 Claude Code 识别、解释并修复在高级 (High) 和严重 (Critical) 审计发现中占绝大多数的四类漏洞： ### 四类 CPI 漏洞 | 类别 | 风险 | 问题所在 | |-------|------|-----------------| | **CPI return-data 伪造** | 严重 | 在未验证生成程序的情况下信任 `get_return_data()`。任何程序都可以写入 return-data 插槽 —— 恶意调用者会在您的程序读取之前替换预言机价格。 | | **任意 CPI** | 高 | 调用由调用者提供的 program id —— 这会导致虚假的 SPL Token 程序以及攻击者控制的代码在受害者金库中执行。 | | **CPI 后账户过期** | 高 | 在未从账本重新加载的情况下，读取被调用者已修改的账户状态。 | | **PDA CPI 签名** | 中高 | 使用非规范 bump 或泄露的签名者种子执行 `invoke_signed` —— 这会导致未经授权的签名。 | ### 核心创新：CPI return-data 伪造 最核心的覆盖重点是 CPI return-data 伪造。它是这四类漏洞中文档最少的，也是在代码审查中最难发现的。其攻击面在于 `set_return_data` / `get_return_data` 系统调用对：在您的程序之前（或由您的程序）调用的任何程序都可以覆盖该插槽。如果 DeFi 程序调用了预言机 CPI，随后在未检查 `program_id == ORACLE_PROGRAM_ID` 的情况下读取 `get_return_data()`，则该程序完全可被利用。 本技能基于一个已在上游修复的真实发现：Anchor CPI return-data 伪造，CVSS 7.5，已在上游修复，在一次涉及 14 个协议的审计的 116 个发现中排名第 1。 同时涵盖了 Anchor 和原生/Pinocchio 模式。 ## 包含内容 ### 技能包 ``` skills/ solana-cpi-safety/ SKILL.md # Routing entry point cpi-return-data-spoofing.md # Crown jewel sub-skill arbitrary-cpi.md # Arbitrary CPI sub-skill account-reload.md # Stale account sub-skill pda-cpi-signing.md # PDA signing sub-skill poc-harness.md # PoC test harness guide cpi-checklist.md # Pre-audit CPI checklist rules/ rust.md # Rust code rule (Cursor .mdc) agents/ cpi-auditor.md # Autonomous CPI audit agent commands/ audit-cpi.md # /audit-cpi command poc/ return-data-spoofing/ # Runnable LiteSVM + TypeScript PoC (incl. Variant B) pinocchio-return-data/ # Runnable LiteSVM PoC (Pinocchio crown-jewel variant) arbitrary-cpi/ # Runnable LiteSVM + TypeScript PoC account-reload/ # Runnable LiteSVM + TypeScript PoC pda-cpi-signing/ # Runnable LiteSVM + TypeScript PoC ``` ### /audit-cpi 命令 在任何 Claude Code 会话中调用 `/audit-cpi`，扫描 Solana 代码库以查找所有四类 CPI 漏洞，并生成包含修复步骤的结构化发现报告。 ### cpi-auditor 代理 一个专用的子代理，执行系统性的 CPI 审计。它将任务路由到针对每种漏洞类别的相应子技能，编写漏洞 PoC 草案，并提出符合 Anchor 或原生/Pinocchio 习惯的修复建议。 ### rust.md 规则 采用 Cursor `.mdc` 格式（包含 `globs:` frontmatter）的 Rust 代码规则。在 Cursor 中，它会在编辑 Rust 文件时自动加载，并将涉及 CPI 的更改路由到相关的子技能和 `cpi-checklist.md`。Claude Code 没有编辑时自动触发规则的机制，因此在那里它是技能引用的参考资料 —— 或者将其放入项目的 `.claude/rules/` 目录中（带有 `paths:` frontmatter）以实现路径范围内的上下文加载。 ### 可运行的 PoC 五个可运行的 PoC 涵盖了四类漏洞 —— 核心类别（return-data 伪造）提供了 Anchor 和 Pinocchio 的双重验证。每个 PoC 都将链上程序（攻击者 + 受害者）与运行 EXPLOIT / DEFENSE / POSITIVE CONTROL（攻击 / 防御 / 阳性对照）用例的 TypeScript LiteSVM 测试套件配对。除非另有说明，程序均为 Anchor 编写： **poc/return-data-spoofing/**（核心内容；6 个用例） - EXPLOIT（攻击）：受害者采用了攻击者程序写入的伪造价格 - DEFENSE（防御）：在生产者检查失败时抛出 `UntrustedProducer` 错误 - POSITIVE CONTROL（阳性对照）：接受来自真实预言机程序的返回数据 - 变体 B（深层堆栈泄露）：一个良性中继程序使更深层次程序的返回数据浮出水面 —— EXPLOIT 采用了深层攻击者的伪造数据，DEFENSE 通过生产者检查拒绝该数据，POSITIVE 则接受真实的预言机数据 **poc/pinocchio-return-data/**（核心内容，Pinocchio；3 个用例） - 与 Anchor return-data PoC 具有相同的漏洞利用和修复方式，基于原始 Pinocchio（`pinocchio::cpi`、`AccountView`、`Address`）编写，并使用 `cargo-build-sbf` 构建 - 一个 `consumer` 程序通过单字节指令鉴别符（0 = 存在漏洞，1 = 已修复）来选择未检查路径或已检查路径 - EXPLOIT 采用攻击者伪造的 `1`；DEFENSE 以 `UntrustedProducer` 拒绝；POSITIVE 接受受信任预言机的 `50_000` **poc/arbitrary-cpi/** - EXPLOIT（攻击）：攻击者替换为虚假的 SPL Token 程序；攻击者控制的代码在金库的 CPI 内部执行 - DEFENSE（防御）：显式的 program_id 检查在任何 CPI 开启之前拒绝替换 - POSITIVE CONTROL（阳性对照）：真实的 SPL Token 程序成功执行 **poc/account-reload/** - EXPLOIT（攻击）：存在漏洞的消费者检查 CPI 之前的余额快照，因此被 CPI 耗尽的金库可以通过偿付能力检查 - DEFENSE（防御）：修复后的消费者在 CPI 之后重新读取数据（即 `reload()` 教训）并拒绝已耗尽的金库 - POSITIVE CONTROL（阳性对照）：保持有偿付能力的部分提款被接受 **poc/pda-cpi-signing/** - EXPLOIT（攻击）：金库 PDA 使用种子 `[b"vault", authority]` 进行签名 (`invoke_signed`)，但从未要求该 authority 签名 —— 攻击者通过在未签名的情况下传递受害者的 pubkey 来抽干受害者的金库 - DEFENSE（防御）：修复后的程序要求 authority 必须签名，从而拒绝未签名的抽干行为 - POSITIVE CONTROL（阳性对照）：真正的 authority 从其自有金库中提款 - 第二个测试文件 (`non-canonical-bump.test.ts`) 涵盖了非规范 bump 面：存在漏洞的程序通过 `invoke_signed` 使用调用者提供的 bump 创建了一个“每用户一个”的注册表 PDA，因此攻击者可以将同一用户注册两次（先规范 bump 然后非规范 bump）以铸造重复账户；修复后的程序通过 `find_program_address` 固定了规范 bump ## 快速开始 ### 安装 一行命令安装（推荐） —— 完整捆绑包（技能 + `/audit-cpi` 命令 + `cpi-auditor` 代理），全局安装（`~/.claude`）： ``` npx @rector-labs/solana-cpi-safety-skill # 改为项目本地使用: npx @rector-labs/solana-cpi-safety-skill --project ``` 仅技能安装，通过开放的 agent-skills 生态系统： ``` npx skills add RECTOR-LABS/solana-cpi-safety-skill ``` 作为原生 Claude Code 插件（完整捆绑包），通过 RECTOR-LABS 市场安装： ``` /plugin marketplace add RECTOR-LABS/claude-plugins /plugin install solana-cpi-safety@rector-labs ``` 从克隆安装（无需 Node）： ``` git clone https://github.com/RECTOR-LABS/solana-cpi-safety-skill.git cd solana-cpi-safety-skill && ./install.sh # or ./install-custom.sh ``` 然后重启 Claude Code。注意：作为插件安装时，命令带有命名空间 `/solana-cpi-safety:audit-cpi`；通过 npx 或 `install.sh` 安装时为 `/audit-cpi`。 ### 运行 PoC 编译后的程序及其密钥对已提交，因此仅使用 Node 即可运行 PoC —— 无需 Solana/Anchor 工具链。 ``` # Return-data 伪造 PoC cd poc/return-data-spoofing npm install npm test ``` 运行 6 个测试，6 个通过（变体 A + 变体 B 深层堆栈）： - EXPLOIT（攻击）：“存在漏洞的消费者信任伪造的返回数据” —— 交易成功，消费者 采用攻击者设定的价格 1（伪造值已在返回数据中确认） - DEFENSE（防御）：“修复后的消费者拒绝攻击者预言机” —— 交易失败并报错 UntrustedProducer - POSITIVE CONTROL（阳性对照）：“修复后的消费者接受合法预言机” —— 交易成功，消费者 读取真实预言机价格 50000 - 变体 B（深层堆栈泄露）：EXPLOIT 通过良性中继程序采用深层攻击者的伪造数据；DEFENSE 通过生产者检查拒绝它；POSITIVE 接受真实的预言机 ``` # 任意 CPI PoC cd poc/arbitrary-cpi npm install npm test ``` 运行 3 个测试，3 个通过： - EXPLOIT（攻击）：“vault_vulnerable 接受 fake_token 程序替换” —— 交易成功， 返回数据字节 0 = 1，证明 fake_token（攻击者程序）已执行 - DEFENSE（防御）：“vault_fixed 拒绝 fake_token 程序替换” —— 交易失败并报错 WrongTokenProgram - POSITIVE CONTROL（阳性对照）：“vault_fixed 接受 real_token” —— 交易成功，返回数据字节 0 = 0 ``` # account-reload (stale-account-after-CPI) PoC cd poc/account-reload && npm install && npm test # pda-cpi-signing (invoke_signed) PoC cd poc/pda-cpi-signing && npm install && npm test # pinocchio-return-data (Pinocchio crown-jewel 变体) PoC cd poc/pinocchio-return-data && npm install && npm test ``` 这些运行具有相同的 EXPLOIT / DEFENSE / POSITIVE CONTROL 结构（每个 3 个测试）。 #### 从源码重建程序（可选） 如果已安装 Anchor 1.0.2 和 Solana 工具链，请在 Anchor `poc//` 目录中运行 `anchor build`。`pinocchio-return-data` PoC 改为使用 `cargo-build-sbf` 构建（有关工具链说明，请参见 CLAUDE.md）。提交的程序密钥对可确保程序 ID 在重新构建后保持稳定。 ### 在 Claude Code 中使用 安装后，在 Solana 项目中打开任何 Claude Code 会话并提问： ``` Audit this program for CPI vulnerabilities /audit-cpi Are there any return-data spoofing risks in programs/my-program/src/lib.rs? Review this CPI call for arbitrary-program substitution ``` ## 添加到 Solana AI Kit 该工具包 (solanabr/solana-ai-kit) 将外部技能注册为 `.claude/skills/ext/` 下的 git 子模块。要添加此技能： ``` git submodule add https://github.com/RECTOR-LABS/solana-cpi-safety-skill.git .claude/skills/ext/solana-cpi-safety ``` 生成的 `.gitmodules` 块（可直接粘贴）： ``` [submodule ".claude/skills/ext/solana-cpi-safety"] path = .claude/skills/ext/solana-cpi-safety url = https://github.com/RECTOR-LABS/solana-cpi-safety-skill.git ``` ## 要求（针对 PoC） 运行 PoC 的要求（主要路径 —— 程序已预编译）： | 工具 | 版本 | |------|---------| | Node.js | >= 20 | 从源代码重建程序（可选）： | 工具 | 版本 | |------|---------| | Anchor | 1.0.2 | | Solana / Agave CLI | 3.x | | Rust | 1.85+ | | Node.js | >= 20 | 技能包（skills/solana-cpi-safety/、commands/、agents/）没有运行时要求 —— 它是纯 Markdown。 ## 仓库结构 ``` solana-cpi-safety-skill/ README.md # This file CLAUDE.md # Contributor guidance LICENSE # MIT install.sh # Standard installer install-custom.sh # Custom-path installer package.json # npm package (@rector-labs/solana-cpi-safety-skill) bin/cli.mjs # Zero-dependency Node installer (npx) test/ # node:test suites (installer + manifest) .claude-plugin/ plugin.json # Claude Code plugin manifest skills/ solana-cpi-safety/ SKILL.md cpi-return-data-spoofing.md arbitrary-cpi.md account-reload.md pda-cpi-signing.md poc-harness.md cpi-checklist.md rules/ rust.md agents/ cpi-auditor.md commands/ audit-cpi.md poc/ return-data-spoofing/ programs/ # Anchor victim + attacker + relay programs tests/ # LiteSVM TypeScript test suite (Variant A + B) pinocchio-return-data/ programs/ # Pinocchio oracle + attacker + consumer programs tests/ # LiteSVM TypeScript test suite arbitrary-cpi/ programs/ # Anchor victim + attacker programs tests/ # LiteSVM TypeScript test suite account-reload/ programs/ # Anchor ledger + consumer programs tests/ # LiteSVM TypeScript test suite pda-cpi-signing/ programs/ # Anchor vault programs tests/ # LiteSVM TypeScript test suite ``` ## RECTOR-LABS Solana 安全套件 此技能是 RECTOR-LABS 三部分 Solana 安全工作流的第一部分 —— 查找漏洞、证明漏洞、响应事件： | 技能 | 阶段 | 状态 | |-------|-------|--------| | **solana-cpi-safety**（此仓库） | 查找 —— 检测并防范 CPI 漏洞类别 | 可用 | | **solana-poc-forge** | 证明 —— 打造可运行的 PoC 和漏洞利用 | 计划中 | | **solana-incident-response** | 响应 —— 分类、控制和披露实时事件 | 计划中 | 这三者均通过共享的 `rector-labs` 市场安装： ``` /plugin marketplace add RECTOR-LABS/claude-plugins /plugin install solana-cpi-safety@rector-labs ``` ## 许可证 MIT —— 详情请参见 [许可证](LICENSE)。 由 [RECTOR-LABS](https://github.com/RECTOR-LABS) 维护。 为 Superteam x Solana AI Kit 赏金而构建。

标签：AI编程辅助, Claude Code, CPI安全, MITM代理, Solana, 区块链安全, 可视化界面, 智能合约审计, 自动化攻击, 防御加固