BradMoonUESTC/finite-monkey-engine

# Finite Monkey Engine v3.0 安全分析流水线，用于代码审计：**规划 → 推理 → 验证**。 结果将持久化到 PostgreSQL，并可以导出为报告。 ## v3.0 更新 - **规划**：移除 RAG / 分块 / 调用图 / 调用树。保留 tree-sitter 函数解析，并使用 Codex CLI 提取业务流程（Gi/Fi）。任务以 **Fi × checklist (rule_key)** 形式持久化。 - **推理**：将主扫描执行切换到 **Codex CLI**（输入：`business_flow_code + prompt`）。输出仍为原始的 **多漏洞 JSON**，随后拆分为 `project_finding`（保持下游逻辑不变）。 - **验证**：基于 Codex 的 `project_finding` 确认，并将结果写回 `validation_status` / `validation_record`。 - **工作区限制**：Codex 始终以 `--cd ` 运行，路径来源于 `src/dataset/agent-v1-c4/datasets.json[project_id].path`。 - **设计文档**：移至 `docs/` 目录。 ## 🚀 v2.0 主要升级 **Finite Monkey Engine v2.0** 带来了显著的架构升级和功能增强： ### 🔥 核心升级 - **🎯 精准语言支持**：聚焦 4 种核心语言（Solidity/Rust/C++/Move），提供最佳分析体验 - **🧠 RAG 架构优化**：采用 LanceDB 合并双表架构，查询效率提升 300% - **📊 智能上下文理解**：多维嵌入技术，显著增强代码理解能力 - **⚡ 性能优化**：统一存储策略，内存减少 50%，提升并发处理能力 - **🔍 深度业务分析**：增强的业务流程可视化与跨合约依赖分析 ## 🎯 概述 Finite Monkey Engine 是一个以 AI 为驱动的代码安全分析平台，**专注于区块链与系统级代码安全审计**。通过集成多种 AI 模型与先进的静态分析技术，为核心编程语言项目提供全面、智能的安全审计解决方案。 ### 🌍 多语言支持 基于 Tree-sitter 解析引擎与函数级分析架构，**v2.0 聚焦 4 种核心语言**，提供最佳分析体验： **✅ 当前完全支持的语言：** - **Solidity** (.sol) — 以太坊智能合约，提供完整的 Tree-sitter 支持 - **Rust** (.rs) — Solana 生态、Substrate、系统级编程 - **C/C++** (.c/.cpp/.cxx/.cc/.C/.h/.hpp/.hxx) — 区块链核心、节点客户端 - **Move** (.move) — Aptos、Sui 区块链语言 - **Go** (.go) — 区块链基础设施、TEE 项目~~ **🔄 计划支持（未来版本）：** - ~~**Cairo** (.cairo) — StarkNet 智能合约语言~~ - ~~**Tact** (.tact) — TON 区块链智能合约~~ - ~~**FunC** (.fc/.func) — TON 区块链原生语言~~ - ~~**FA** (.fr) — 函数式智能合约语言~~ - ~~**Python** (.py) — Web3、DeFi 后端项目~~ - ~~**JavaScript/TypeScript** (.js/.ts) — Web3 前端、Node.js 项目~~ - ~~**Java** (.java) — 企业区块链应用~~ ## 🚀 v2.0 核心功能 ### 🧠 增强的 AI 驱动分析 - **多模型协作**：Claude-4 Sonnet、GPT-4 等 AI 模型协同工作 - **RAG 增强理解**：基于 LanceDB 的多维上下文感知技术 - **深度业务逻辑分析**：深入理解 DeFi 协议、治理机制与代币经济学 - **智能漏洞发现**：AI 辅助的复杂漏洞模式识别 ### 🔍 全面的安全检测系统 - **精准漏洞检测**：聚焦核心语言，实现更准确的漏洞识别 - **跨合约深度分析**：多合约交互分析与复杂依赖跟踪 - **业务场景审查**：针对不同 DeFi 场景的专业安全分析 - **智能误报过滤**：AI 辅助降低误报率，提升分析准确性 ### 🛠 精准语言架构 - **核心语言聚焦**：为 Solidity/Rust/C++/Move 提供专用框架 - **模块化设计**：规划、验证、上下文与分析模块 - **Tree-sitter 解析**：支持核心语言的高精度解析 ## 📁 项目结构 ``` finite-monkey-engine/ ├── src/ │ ├── planning/ # Task planning and business flow analysis │ ├── validating/ # Vulnerability detection and validation │ ├── context/ # Context management and RAG processing │ ├── reasoning/ # Analysis reasoning and dialogue management │ ├── dao/ # Data access objects and entity management │ ├── library/ # Parsing libraries and utilities │ ├── openai_api/ # AI API integrations │ └── prompt_factory/ # Prompt engineering and management ├── knowledges/ # Domain knowledge base ├── scripts/ # Utility scripts └── docs/ # Documentation ``` ## 🚀 快速开始 ### 先决条件 - **Python 3.10+** - **PostgreSQL 13+**（用于存储分析结果） - **AI API 密钥**（支持 OpenAI、Claude、DeepSeek 等兼容服务） ### 安装 ``` # 1. Clone the repository git clone https://github.com/your-org/finite-monkey-engine.git cd finite-monkey-engine # 2. Install Python dependencies pip install -r requirements.txt # 3. Configure environment variables cp env.example .env # 编辑 .env 文件以添加您的 API 密钥和数据库配置 # 4. Initialize database psql -U postgres -d postgres -f project_task.sql # 5. Configure project dataset # 编辑 src/dataset/agent-v1-c4/datasets.json 以添加您的项目配置 # 6. Run analysis python src/main.py ``` ## 📊 使用指南 ### 数据库初始化 使用提供的 SQL 文件初始化 PostgreSQL 数据库： ``` # 连接到 PostgreSQL 数据库 psql -U postgres -d postgres # 执行 SQL 文件以创建表结构 \i project_task.sql # 或直接使用命令行 psql -U postgres -d postgres -f project_task.sql ``` ### 项目配置 在 `src/dataset/agent-v1-c4/datasets.json` 中配置你的项目： ``` { "your_project_id": { "path": "your_project_folder_name", "files": [], //no need to set, disable in future "functions": [], //no need to set, disable in future "exclude_in_planning": "false", //no need to set to true, disable in future "exclude_directory": [] //no need to set, disable in future } } ``` ### 运行分析 1. **设置项目 ID**：在 `src/main.py` 中配置项目 ID ``` project_id = 'your_project_id' ``` 2. **执行分析**： ``` python src/main.py ``` 3. **查看结果**： - 数据库中的详细分析记录 - `output.xlsx` 报告文件 - Mermaid 业务流程图（若启用） ## 🔧 配置 ### 快速配置 1. **复制环境模板**： cp env.example .env 2. **编辑 `.env` 文件**，填入你的 API 密钥与偏好设置 ### 核心环境变量 ``` # Database Configuration (Required) DATABASE_URL=postgresql://postgres:1234@127.0.0.1:5432/postgres # Codex (Required for v3.0 planning/reasoning/validation) CODEX_MODEL=gpt-5.2 CODEX_SANDBOX=read-only CODEX_ASK_FOR_APPROVAL=never CODEX_TIMEOUT_SEC=1800 # Legacy model config (still used by some auxiliary flows) OPENAI_API_BASE="api.openai-proxy.org" # LLM proxy platform OPENAI_API_KEY="sk-xxxxxx" # API key # Scan Mode Configuration SCAN_MODE=COMMON_PROJECT_FINE_GRAINED # Recommended mode: Common project checklist fine-grained # Available modes: PURE_SCAN (Pure scanning) SCAN_MODE_AVA=False # Advanced scan mode features COMPLEXITY_ANALYSIS_ENABLED=True # Enable complexity analysis # Performance Tuning MAX_THREADS_OF_SCAN=10 # Maximum threads for scanning phase MAX_THREADS_OF_CONFIRMATION=50 # Maximum threads for confirmation phase BUSINESS_FLOW_COUNT=4 # Business flow repeat count (hallucination triggers) # Advanced Feature Configuration IGNORE_FOLDERS=node_modules,build,dist,test,tests,.git # Folders to ignore # Checklist Configuration CHECKLIST_PATH=src/knowledges/checklist.xlsx # Path to checklist file CHECKLIST_SHEET=Sheet1 # Checklist worksheet name # Run control (v3.0) CMD=detect_vul # detect_vul / planning_only STOP_AFTER_PLANNING=false # true: stop after planning (before reasoning) ``` ### AI 模型配置详情 基于 `src/openai_api/model_config.json` 的实际配置： **警告** 必须根据你的 LLM 中心设置模型名称！ **警告** 必须根据你的 LLM 中心设置模型名称！ **警告** 例如在 OpenRouter 上，Sonnet 4 需设置为 `anthropic/sonnet-4` ``` { "openai_general": "gpt-4.1", "code_assumptions_analysis": "claude-sonnet-4-20250514", "vulnerability_detection": "claude-sonnet-4-20250514", "initial_vulnerability_validation": "deepseek-reasoner", "vulnerability_findings_json_extraction": "gpt-4o-mini", "additional_context_determination": "deepseek-reasoner", "comprehensive_vulnerability_analysis": "deepseek-reasoner", "final_vulnerability_extraction": "gpt-4o-mini", "structured_json_extraction": "gpt-4.1", "embedding_model": "text-embedding-3-large" } ``` ### 推荐配置方案 #### 🚀 快速启动（小型项目 < 50 个文件） ``` SCAN_MODE=PURE_SCAN COMPLEXITY_ANALYSIS_ENABLED=False MAX_THREADS_OF_SCAN=3 BUSINESS_FLOW_COUNT=2 ``` #### 🏢 企业级（大型项目 > 100 个文件） ``` SCAN_MODE=COMMON_PROJECT_FINE_GRAINED COMPLEXITY_ANALYSIS_ENABLED=True MAX_THREADS_OF_SCAN=8 MAX_THREADS_OF_CONFIRMATION=30 BUSINESS_FLOW_COUNT=4 ``` #### 💰 成本优化 ``` SCAN_MODE=PURE_SCAN BUSINESS_FLOW_COUNT=1 MAX_THREADS_OF_SCAN=3 MAX_THREADS_OF_CONFIRMATION=10 COMPLEXITY_ANALYSIS_ENABLED=False ``` ## 🎯 使用场景 ### 区块链与 Web3 项目 - **智能合约安全**：Solidity、Rust、Move 合约分析 - **DeFi 协议分析**：AMM、借贷、治理机制审查 - **跨链应用**：桥接安全、多链部署分析 - **NFT 与游戏**：铸造逻辑、市场集成安全 ### 传统软件项目 - **Web3 后端**：Python/Node.js API 安全分析 - **区块链基础设施**：Go/C++ 节点与客户端安全 - **企业应用**：Java 企业区块链应用 - **系统级代码**：C/C++ 核心组件与 TEE 项目 ### 多语言项目分析 - **多语言代码库**：跨语言依赖分析 - **微服务架构**：多服务安全评估 - **全栈应用**：前端、后端与合约集成安全 ## 📊 分析报告 该平台生成全面的分析报告，包括： - **安全漏洞报告**：带严重等级评定的详细漏洞发现 - **业务流程图**：合约交互的可视化表示 - **Gas 优化建议**：性能改进建议 - **最佳实践合规性**：遵循安全标准与指南 ## 🧪 测试 运行测试套件： ``` # Unit tests python -m pytest tests/ # Integration tests python -m pytest tests/integration/ # Coverage report python -m pytest --cov=src tests/ ``` ## 🤝 贡献 我们欢迎贡献！请参考我们的 [贡献指南](CONTRIBUTING.md) 获取详细信息。 1. 叉取仓库 2. 创建功能分支 (`git checkout -b feature/amazing-feature`) 3. 提交更改 (`git commit -m 'Add amazing feature'`) 4. 推送到分支 (`git push origin feature/amazing-feature`) 5. 发起拉取请求 ## 📄 许可证 本项目采用 Apache License 2.0 许可协议 — 详见 [LICENSE](LICENSE) 文件。 ## 🙏 感谢 - **ANTLR4**：提供 Solidity 解析 - **Claude AI**：提供高级代码理解能力 - **Mermaid**：提供业务流程可视化 - **OpenAI**：提供 AI 驱动的分析能力 ## 📞 联系 - **邮箱**：nerbonic@gmail.com - **Twitter**：[@xy9301](https://x.com/xy9301) - **Telegram**：[https://t.me/+4-s4jDfy-ig1M2Y1](https://t.me/+4-s4jDfy-ig1M2Y1) ## 🆕 v2.0 发行说明 ### 主要升级 - **核心语言聚焦**：专注于 Solidity/Rust/C++/Move，提供最佳分析体验 - **RAG 架构革命**：LanceDB 合并双表架构，性能提升 300% - **智能嵌入**：多维代码理解，显著提升分析精度 - **架构优化**：内存减少 50%，支持更大规模项目 ### 迁移指南 - v2.0 完全向后兼容，无需配置更改 - 不支持的语言文件将被自动跳过，不影响系统运行 - 建议更新配置文件以获得最佳性能体验 **🎉 Finite Monkey Engine v2.0 — 让代码安全分析更智能、更专业、更高效！**

标签：AI安全分析, C++, Codex CLI, Fi检查表, IPv6支持, LanceDB, Move, PostgreSQL, RAG优化, Rust, Solidity, SQL查询, 上下文理解, 业务流可视化, 业务流提取, 云安全监控, 内存优化, 函数级解析, 区块链安全, 向量数据库, 多维度嵌入, 多语言支持, 大模型, 安全审计平台, 安全测试框架, 工作区限制, 性能优化, 报告导出, 数据擦除, 智能合约审计, 树解析, 检测绕过, 测试用例, 漏洞JSON, 结果持久化, 网络流量审计, 设计文档, 跨合约依赖分析, 逆向工具, 静态分析