clarity-audit

Clarity 审计技能

针对 Clarity 智能合约的结构化安全审计。提供全面审查，涵盖正确性、安全漏洞、设计问题和部署就绪情况。既可作为独立技能使用（输出结构化 JSON），也可作为 clarity-expert Agent 的基础（支持开放式推理）。

用法

这是一项仅包含文档的技能。Agent 会阅读此文件以了解审计框架，并通过技能框架或 clarity-expert Agent 调用它。下方的 CLI 接口说明了计划中的实现。

bun run clarity-audit/clarity-audit.ts <subcommand> [options]

子命令

audit

对 Clarity 合约运行完整的结构化审计。

bun run clarity-audit/clarity-audit.ts audit --source <path-to-file.clar> [--contract-id <deployed-contract-id>] [--severity-threshold <level>]

选项：

• --source（必需）— 要审计的 .clar 源文件路径
• --contract-id（可选）— 用于链上验证的已部署合约 ID；启用已部署合约与源代码的交叉比对
• --severity-threshold（可选）— 要报告的最低严重级别：critical、high、medium、low（默认：low）

输出：

{
  "file": "contracts/my-contract.clar",
  "summary": "Token transfer contract with admin controls and minting capability",
  "verdict": "CONDITIONAL_PASS",
  "riskLevel": "MEDIUM",
  "stats": {
    "publicFunctions": 5,
    "readOnlyFunctions": 3,
    "privateFunctions": 2,
    "maps": 2,
    "dataVars": 1,
    "constants": 8
  },
  "whatWorksCorrectly": [
    "Transfer function uses try! for error propagation",
    "Admin functions check tx-sender against owner constant",
    "Events follow structured notification/payload format"
  ],
  "bugs": [
    {
      "severity": "high",
      "title": "Unbounded mint allows infinite token supply",
      "location": {"function": "mint", "line": 45},
      "description": "The mint function has no supply cap check. Any admin can mint unlimited tokens.",
      "recommendation": "Add MAX_SUPPLY constant and check (< (+ current-supply amount) MAX_SUPPLY) before minting",
      "category": "logic"
    }
  ],
  "designConcerns": [
    {
      "severity": "medium",
      "title": "Single admin with no succession plan",
      "description": "CONTRACT_OWNER is set at deploy time with no transfer mechanism",
      "recommendation": "Add set-admin function with two-step transfer (propose + accept)"
    }
  ],
  "gasAnalysis": {
    "mostExpensiveFunction": "batch-transfer",
    "concern": "fold over list of 200 recipients may approach block limits"
  }
}

quick-check

运行轻量扫描，仅关注严重和高严重级别的问题。

bun run clarity-audit/clarity-audit.ts quick-check --source <path-to-file.clar>

选项：

• --source（必需）— .clar 源文件路径

输出：

{
  "file": "contracts/my-contract.clar",
  "criticalIssues": 0,
  "highIssues": 1,
  "quickVerdict": "REVIEW_NEEDED",
  "findings": [
    {
      "severity": "high",
      "title": "Unbounded mint allows infinite token supply",
      "line": 45,
      "fix": "Add MAX_SUPPLY cap"
    }
  ]
}

function-review

详细审计单个函数，并进行颜色编码的风险评估。

bun run clarity-audit/clarity-audit.ts function-review --source <path-to-file.clar> --function <function-name>

选项：

• --source（必需）— .clar 源文件路径
• --function（必需）— 要审查的函数名称

输出：

{
  "function": "transfer",
  "visibility": "public",
  "riskColor": "ORANGE",
  "riskReason": "Token transfer with external call",
  "parameters": [
    {"name": "amount", "type": "uint", "validated": true},
    {"name": "to", "type": "principal", "validated": false}
  ],
  "checks": [
    {"check": "Input validation", "status": "partial", "detail": "amount checked but recipient not validated"},
    {"check": "Proper sender check", "status": "pass", "detail": "Uses tx-sender correctly"},
    {"check": "Error propagation", "status": "pass", "detail": "Uses try! for ft-transfer?"},
    {"check": "Post-condition safe", "status": "warn", "detail": "No post-condition hints in contract"},
    {"check": "Reentrancy safe", "status": "pass", "detail": "State changes before external calls"}
  ],
  "recommendation": "Add recipient validation (not contract principal) if transfers should be restricted to standard principals"
}

风险颜色框架

颜色	含义	示例
GREEN	无害的只读操作	get-balance、get-stats
YELLOW	设有适当保护的状态变更	带身份验证的 check-in、带快照的 vote
ORANGE	代币转账、外部调用	transfer、swap、任何 contract-call?
RED	严重风险——管理员函数、金库访问	withdraw、mint、set-admin、upgrade

审计类别

类别	涵盖内容
logic	行为错误、缺少检查、条件错误
security	重入、溢出、绕过访问控制、资金锁定
design	架构问题、功能缺失、升级相关问题
gas	可能超出区块成本限制的函数
standards	SIP 合规性、事件格式、命名约定

严重级别

级别	标准
critical	资金面临风险、合约可能被永久锁死、任何人都可利用
high	严重逻辑错误、访问控制问题、经济攻击
medium	影响功能或用户体验的非严重问题
low	违反最佳实践、代码质量问题、文档缺漏

备注

• 此技能会生成结构化输出，供自动化处理
• 如需开放式安全推理和多合约分析，请使用 clarity-expert Agent
• 审计仅进行静态分析，不会执行合约
• 部署前务必结合 clarity-check 进行验证
• 对于生产环境中的关键合约，请通过 clarity-test-scaffold 补充 RV 模糊测试
• 参考：pbtc21/publisher-succession#1，查看审计输出示例