clarity-audit

Clarity 監査スキル

Clarity スマートコントラクトを対象とした、体系的なセキュリティ監査です。正確性、セキュリティ上の脆弱性、設計上の懸念事項、デプロイ準備状況を網羅した包括的なレビューを行います。単独のスキル（構造化された JSON 出力）としても、clarity-expert エージェントの基盤（自由形式の推論）としても使用できるように設計されています。

使用方法

これはドキュメントのみのスキルです。エージェントはこのファイルを読んで監査フレームワークを理解し、スキルフレームワークまたは clarity-expert エージェントを通じて実行します。以下の 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

重大度が critical と high の問題に絞った、簡易スキャンを実行します。

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 エージェントを使用してください
• 監査は静的解析のみを行い、コントラクトは実行しません
• デプロイ前の検証では、必ず clarity-check と併用してください
• 本番環境で重要なコントラクトでは、clarity-test-scaffold を使用した RV ファズテストも追加で実施してください
• 参考：監査出力の例については、pbtc21/publisher-succession#1 を参照してください