ACaiSec/acai-dag-auditor

# ACAI-DAG-Auditor 一个基于 DAG 的工作流引擎，用于自动化 Solidity 智能合约安全审计。本项目通过数据流驱动的调度系统协调多阶段分析，从原始源代码生成 Code4rena 风格的审计报告。 **调用方式：** 在 Claude Code 中，从目标 Solidity 项目的根目录运行 `/acai-dag-auditor`。该技能完全在项目目录中执行，并将所有产物写入 `./acai-dag-auditor/`。 ## 安装说明 1. 克隆此仓库： git clone https://github.com/ACaiSec/acai-dag-auditor.git 2. 将 `acai-dag-auditor/` 技能文件夹复制到你的 Claude Code 技能目录中： cp -r acai-dag-auditor/acai-dag-auditor ~/.claude/skills/ 3. 重启 Claude Code 或重新加载技能。该技能现在可以作为 `/acai-dag-auditor` 使用。 ## 概述 ACAI-Audit 将审计视为一个由专门分析节点组成的有向无环图 (DAG)。每个节点消费上游节点生成的产物，并生成新产物供下游消费。运行时会自动解析依赖、并行执行独立任务，并在编译或其他步骤失败时处理回退路径。 核心理念是**数据流驱动的调度**：DAG 不是以命令式代码硬编码的，而是从每个节点清单 (`node.yaml`) 中的产物声明推断出来的。这使得工作流是声明式的、可扩展的且自我文档化的。 ## DAG 工作流设计 ### 执行模型 1. **发现** — 运行时读取 `workflow.dag.yaml` 以获取节点列表，然后扫描每个 `node.yaml` 以构建隐式 DAG。只要节点声明了带有 `source: upstream:` 的输入，就会创建一条边。 2. **状态解析** — 每个节点的状态通过检查 `./acai-dag-auditor/artifacts//` 下的文件系统来确定： - `done` — 所有已声明的 `outputs` 均存在 - `failed` — 存在 `.failed` 标记 - `pending` — 产物目录为空或不存在 3. **就绪评估** — 当 `required: true` 的输入全部就绪（存在于工作区或由上游节点生成）时，`pending` 节点将变为 `ready` 状态。 4. **执行** — 就绪节点被分派给子代理（每次最多 `max_parallel_nodes` 个）。每个子代理在被审计项目的根目录中运行，读取其 `main.md` 提示词，并将输出写入其产物目录。 5. **重新评估** — 完成后，运行时重新扫描所有 `pending` 节点。新满足的依赖会触发其他节点。此过程重复进行，直到每个节点都处于 `done`、`failed` 或 `skipped` 状态。 ### 基于产物存在性的分支 节点通过选择生成哪些文件来控制下游执行。如果节点 A 生成 `findings-set-a.md`，则下游节点 B（其输入为 `findings-set-a.md`）将变为就绪状态。如果节点 A 未生成 `findings-set-b.md`，则下游节点 C 将永远无法收到其必需的输入，并最终标记为 `skipped`。这允许在工作流定义中无需显式 `if` 语句即可实现条件路径。 ### 审计 DAG ``` env_setup ──────► project_parsing │ ├─► fund_flow_analysis ─────┐ │ ├──► summary_output └─► business_flow_analysis ──┘ ``` | Node | Tag | Responsibility | |------|-----|----------------| | **env_setup** | `parsing` | 检测项目的框架 (Foundry, Hardhat, Truffle)，安装依赖并尝试编译。在 3 次尝试失败后回退到仅源代码路径。 | | **project_parsing** | `parsing` | 编译合约，尽可能生成 AST，并提取压缩的调用图以及结构化的业务流链。如果编译成功则使用 AST；否则回退到仅源代码的启发式方法。 | | **fund_flow_analysis** | `finding` | 检查每个业务流是否存在资金流不平衡、缺少内部账本更新以及资金冻结/损失场景。 | | **business_flow_analysis** | `finding` | 检查业务流程设计中的状态转换完整性、跨流一致性以及冻结/DoS 风险。 | | **summary_output** | `output` | 对所有上游分析节点的发现进行去重，验证每个问题 (true positive / false positive / downgrade)，并将验证后的问题格式化为单独的 Code4rena 风格报告以及一份汇总 Markdown 文件。 | ### 输入与输出流 ``` env_setup ├─ outputs: compilation_output.json (or build_failed.md on failure) │ project_parsing ├─ inputs: compilation_output.json [optional, upstream:env_setup] │ build_failed.md [optional, upstream:env_setup] ├─ outputs: project_overview.md │ call_graph.yaml │ business_flows.yaml │ fund_flow_analysis ├─ inputs: project_overview.md [required, upstream:project_parsing] │ business_flows.yaml [required, upstream:project_parsing] │ call_graph.yaml [required, upstream:project_parsing] ├─ outputs: fund-flow-analysis/ (individual finding reports) │ business_flow_analysis ├─ inputs: project_overview.md [required, upstream:project_parsing] │ business_flows.yaml [required, upstream:project_parsing] │ call_graph.yaml [required, upstream:project_parsing] ├─ outputs: business-flow-analysis/ (individual finding reports) │ summary_output ├─ inputs: fund-flow-analysis/ [required, upstream:fund_flow_analysis] │ business-flow-analysis/ [required, upstream:business_flow_analysis] ├─ outputs: deduplicated_findings.json verified_findings.json findings/ (Code4rena-style reports) report_summary.md ``` ## 开发指南 ### 仓库布局 ``` . ├── README.md ├── LICENSE ├── .gitignore └── acai-dag-auditor/ # Skill implementation ├── workflow.dag.yaml # Top-level workflow manifest ├── SKILL.md # Runtime execution specification ├── nodes/ │ ├── env_setup/ │ │ ├── node.yaml # Node manifest (inputs, outputs, execution config) │ │ └── main.md # Prompt / instruction for the subagent │ ├── project_parsing/ │ │ ├── node.yaml │ │ ├── main.md │ │ └── prompts/ # Additional prompt fragments │ ├── fund_flow_analysis/ │ ├── business_flow_analysis/ │ └── summary_output/ └── template/ ├── dag.template.yaml # Template for new workflows └── node.template.yaml # Template for new nodes ``` ### 添加新节点 1. **创建节点目录** mkdir acai-dag-auditor/nodes/ 2. **编写 `node.yaml`**，以 `acai-dag-auditor/template/node.template.yaml` 作为参考： id: your_node_id tag: parsing | finding | output description: artifacts: output_dir: ./acai-dag-auditor/artifacts// inputs: - name: source: upstream: # or workspace / external path: required: true | false description: outputs: - name: path: format: json | markdown | yaml | text description: execution: kind: llm # current runtime supports llm prompts prompt: main.md completion: gate: type: llm_judge # or schema / manual instruction: 3. **编写 `main.md`** — 指导子代理的提示词文档。它应当： - 引用在 `node.yaml` 中列出的输入 - 描述分析或转换任务 - 指定确切的输出文件和格式 - 包含任何特定领域的约束（例如，“仅分析外部函数”） 4. **在 `acai-dag-auditor/workflow.dag.yaml` 中注册节点** nodes: - id: your_node_id module: acai-dag-auditor/nodes/your_node_id 5. **声明上游依赖**，方法是在新节点的 `inputs` 中设置 `source: upstream:`。运行时会自动推断 DAG 边；不需要其他连接操作。 ### 设计新的工作流 从头设计 DAG 时，请遵循此模式： 1. **将问题分解**为离散阶段 (解析 → 分析 → 综合 → 输出)。 2. **为节点分配标签**（标签是用户定义的约定，运行时不强制执行）： - `parsing` — 摄取和结构化原始数据 - `finding` — 检测特定问题类别 - `output` — 整合、去重和格式化 3. **保持节点单一职责**。一个试图同时检测重入和访问控制漏洞的节点，不仅难以编写正确的提示词，也难以复用。 4. **为回退方案使用可选输入**。如果上游步骤可能会失败（例如编译），请将其输出声明为 `required: false`，并让下游节点调整其策略。 5. **利用基于产物存在性的分支**。节点可以根据其发现的内容生成不同的输出文件。下游节点仅在其特定的必需输入出现时才会被激活。 6. **在 `acai-dag-auditor/workflow.dag.yaml` 中设置 `max_parallel_nodes`**，以基于成本/速度权衡进行配置。独立的分析节点（例如 `fund_flow_analysis` 和 `business_flow_analysis`）将并发运行。 ### 提示词工程技巧 - 将可复用的提示词片段放在 `prompts/` 子目录中，并在 `main.md` 中引用它们。 - 当节点消费结构化数据时，包含 AST 压缩模板或 schema 定义（参见 `acai-dag-auditor/nodes/project_parsing/prompts/ast_compress_template.yaml` 示例）。 - 明确指定输出文件路径；完成门控会检查它们是否存在。 ## 许可证 本项目基于 GNU General Public License v3.0 授权。有关详细信息，请参阅 [LICENSE](LICENSE)。

标签：AI代码审计, C2, CISA项目, Claude Code, Code4rena, DAG, DeFi安全, EVM, GNU通用公共许可证, Node.js, Solidity, Web3安全, YAML, 云安全监控, 以太坊, 任务编排, 安全库, 安全报告生成, 工作流引擎, 数据流驱动, 智能合约审计, 有向无环图, 自动化分析, 调度系统, 跨站脚本, 静态分析