building-secure-contracts 快速入门

Trail of Bits 安全专家沉淀的合约审计 Skill,让 AI 在写 Solidity/Cosmos/Substrate 代码时主动规避高危漏洞。

这是什么?解决什么问题?

building-secure-contracts 是 Trail of Bits 旗下 skills 仓库中的一个核心 Skill,专注智能合约安全。它把 6 条主流公链(Ethereum/Solana/Cosmos/Polkadot/NEAR/Tezos)上常见的漏洞模式——重入、整数溢出、权限错误、签名重放、状态机缺陷、Oracle 操纵等——系统性地整理成”合约作者 + 审计者”双向可用的检查清单。

对小白来说,这个 Skill 解决的是”我不知道合约里埋了多少雷”的问题。即使你只写过简单 ERC20,也建议在部署前让 AI 用这个 Skill 走一遍代码,能提前发现 80% 的低级错误。

准备工作

• 支持 Agent:Claude Code(主推)、支持 Skills 协议的 Agent。
• 运行环境:Solidity 0.8+ / Rust(Solana/NEAR)/ Go(Cosmos)对应工具链。
• 目标项目:一份待审计的智能合约代码仓库。
• 可选工具:Slither(Mythril)用于本地二次验证。

3 步快速上手

第 1 步:获取 Skill

# 整仓库克隆
git clone https://github.com/trailofbits/skills.git

# 单独拷贝该 Skill
cp -r skills/building-secure-contracts ~/.claude/skills/

第 2 步:在 Claude Code 中调用

cd your-contract-repo
claude

在对话中:

请用 building-secure-contracts Skill 审查 contracts/Vault.sol,关注重入、权限、Oracle 操纵三类风险。

模型会按 Trail of Bits 的检查表逐项扫描,输出含 CVE 编号、修复建议的报告。

第 3 步:交叉验证

用 Slither 跑一次本地扫描:

pip install slither-analyzer
slither contracts/Vault.sol

把 AI 报告与 Slither 结果对比,差异点就是深入分析的重点。

常见踩坑

1. Solidity 版本误用:^0.8.0 之后内置溢出检查,但若用 unchecked 块,Skill 提示的风险可能”看似消失”实则仍存,务必告诉 AI 哪些地方用了 unchecked。
2. 链类型选错:同一段代码在 Ethereum 与 NEAR 上风险面完全不同,prompt 里要明确链类型。
3. 私有函数被忽略:很多审计者只看 public/external,Trail of Bits 强调 internal/private 也要扫,因为它们的状态修改链路也是攻击面。
4. 忽略升级代理:UUPS/Transparent Proxy 模式带来额外的存储冲突风险,Skill 有专门章节,别漏。
5. 不读 CVE 编号:Skill 输出里的 CVE/Wiki 链接,务必点开看原始披露细节,避免”道听途说”。
6. 把它当万能工具:它给的是模式匹配,不是形式化验证;真正高价值合约建议走人工审计。

初级用法

• 写完即审:每次合并合约代码前,跑一次 Skill 评审,把发现的问题当 PR 评审项。
• 学习样本库:Skill 内置的 examples/ 目录收集了各类典型漏洞的最小复现,适合教学。
• 审计报告模板:用 Skill 输出的报告格式作为标准审计报告骨架,省去文档工作。

高级玩法

• CI 集成:把 Slither + 该 Skill 串到 GitHub Actions,PR 触发自动审计,严重级别 fail pipeline。
• 多链扫描:同一段业务逻辑在 Solidity/Cosmos/Substrate 上各扫一遍,横向对比风险面。
• 漏洞复现:Skill 给出的 PoC 建议结合 Foundry 写最小复现测试,把”理论漏洞”变成”可运行测试”。

小技巧

• 把 Skill 报告保存为 Markdown,放进 docs/audits/ 目录,后续 code-review 有据可查。
• 配合 Slither 的 --detect 参数,聚焦高危检测项,减少噪音。
• 关注 Trail of Bits 博客,他们持续更新新漏洞模式。
• 升级 OpenZeppelin 时特别提示 AI 关注”存储布局变更”,Skill 有专门提醒。
• 别在主网部署前仅靠 Skill 评审,至少再加一次人工或第三方审计。

常见问题 FAQ

Q1: 这个 Skill 跟 building-secure-contracts 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: building-secure-contracts 来自 TrailOfBits,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 building-secure-contracts 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• 官方仓库:https://github.com/trailofbits/skills
• 该 Skill 目录:https://github.com/trailofbits/skills/tree/main/skills/building-secure-contracts
• Trail of Bits 博客:https://blog.trailofbits.com/
• Slither 工具:https://github.com/crytic/slither
• 知名合约审计案例:https://github.com/trailofbits/publications

进一步阅读与延伸

如果你想深入了解 Trail of Bits 这家公司的审计方法论,除了这个 Skill 之外,还可以关注他们的几份公开出版物。

第一,《DeFi 安全手册》(https://github.com/trailofbits/publications) 里有大量真实合约漏洞案例,每个案例都附”攻击手法 + 修复方案 + 单元测试”,学习价值极高。

第二,Slither 的静态分析器内置了几百条检测规则,Skill 评审时建议配合 slither --detect reentrancy-eth,reentrancy-no-eth,arbitrary-send-eth 等参数,聚焦高危检测项。

第三,Foundry(https://github.com/foundry-rs/foundry) 是写 Solidity 测试和 PoC 的最佳工具。建议把 Skill 给出的每个 PoC 建议都写成 Foundry 测试,放进 test/ 目录,作为回归测试长期运行。

第四,关注 EIPs(Ethereum Improvement Proposals)中标记为”安全相关”的部分,比如 EIP-2535(Diamond Standard)就带来很多新攻击面。

与其它安全 Skill 的搭配

• constant-time-analysis:写加密相关合约时联动使用,确保签名验证等恒定时间。
• security-and-hardening:合约后端服务的通用安全加固,涵盖 OWASP。
• static-analysis:用 Semgrep 跑 Solidity 规则集,与 Skill 输出做交叉验证。
• zeroize-audit:虽然主要针对 Rust,合约中处理私钥的链下组件也建议审查。

实战建议

1. 每次合并合约前必跑:把 Skill 评审当作 PR 必过的检查项,类似单元测试。
2. 漏洞复现进 CI:Skill 给出的 PoC 写成 Foundry 测试,跑在 CI 上,作为长期防护。
3. 学习经典漏洞库:SWC Registry(Smart Contract Weakness Classification)整理了 100+ 已知漏洞,Skill 评审时会引用。
4. 关注 OpenZeppelin 升级:OpenZeppelin 升级时常常有 breaking change,Skill 会主动提示。
5. 多语言适配:同一段业务逻辑在 Ethereum(Solidity)与 NEAR(Rust)上各扫一遍,对比风险面。

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。