finite-monkey-engine

finite-monkey-engine

AI engine for smart contract audit

Stars: 305

Visit
 screenshot

FiniteMonkey is an advanced vulnerability mining engine powered purely by GPT, requiring no prior knowledge base or fine-tuning. Its effectiveness significantly surpasses most current related research approaches. The tool is task-driven, prompt-driven, and focuses on prompt design, leveraging 'deception' and hallucination as key mechanics. It has helped identify vulnerabilities worth over $60,000 in bounties. The tool requires PostgreSQL database, OpenAI API access, and Python environment for setup. It supports various languages like Solidity, Rust, Python, Move, Cairo, Tact, Func, Java, and Fake Solidity for scanning. FiniteMonkey is best suited for logic vulnerability mining in real projects, not recommended for academic vulnerability testing. GPT-4-turbo is recommended for optimal results with an average scan time of 2-3 hours for medium projects. The tool provides detailed scanning results guide and implementation tips for users.

README:

Finite Monkey Engine v2.0

An AI-Powered Code Security Analysis Platform

๐Ÿš€ v2.0 Major Upgrades

Finite Monkey Engine v2.0 brings significant architectural upgrades and feature enhancements:

๐Ÿ”ฅ Core Upgrades

  • ๐ŸŽฏ Precision Language Support: Focus on 4 core languages (Solidity/Rust/C++/Move) for optimal analysis experience
  • ๐Ÿง  RAG Architecture Optimization: New LanceDB merged 2-table architecture with 300% query efficiency improvement
  • ๐Ÿ“Š Intelligent Context Understanding: Multi-dimensional embedding technology, significantly enhanced code comprehension
  • โšก Performance Optimization: Unified storage strategy, 50% memory reduction, improved concurrent processing
  • ๐Ÿ” Deep Business Analysis: Enhanced business flow visualization and cross-contract dependency analysis

๐ŸŽฏ Overview

Finite Monkey Engine is an advanced AI-driven code security analysis platform focused on blockchain and system-level code security auditing. By integrating multiple AI models and advanced static analysis techniques, it provides comprehensive, intelligent security auditing solutions for core programming language projects.

๐ŸŒ Multi-Language Support

Built on Tree-sitter parsing engine and function-level analysis architecture, v2.0 focuses on 4 core languages for optimal analysis experience:

โœ… Currently Fully Supported Languages:

  • Solidity (.sol) - Ethereum smart contracts with complete Tree-sitter support
  • Rust (.rs) - Solana ecosystem, Substrate, system-level programming
  • C/C++ (.c/.cpp/.cxx/.cc/.C/.h/.hpp/.hxx) - Blockchain core, node clients
  • Move (.move) - Aptos, Sui blockchain language
  • Go (.go) - Blockchain infrastructure, TEE projects~~

๐Ÿ”„ Planned Support (Future Versions):

  • Cairo (.cairo) - StarkNet smart contract language
  • Tact (.tact) - TON blockchain smart contracts
  • FunC (.fc/.func) - TON blockchain native language
  • FA (.fr) - Functional smart contract language
  • Python (.py) - Web3, DeFi backend projects
  • JavaScript/TypeScript (.js/.ts) - Web3 frontend, Node.js projects
  • Java (.java) - Enterprise blockchain applications

๐Ÿ’ก v2.0 Design Philosophy: Focus on core languages to provide deeply optimized analysis capabilities. Based on function-granularity code analysis architecture, theoretically extensible to any programming language. Future versions will gradually support more languages.

๐Ÿš€ v2.0 Key Features

๐Ÿง  Enhanced AI-Powered Analysis

  • Multi-Model Collaboration: Claude-4 Sonnet, GPT-4 and other AI models working intelligently together
  • RAG-Enhanced Understanding: Multi-dimensional context-aware technology based on LanceDB
  • Deep Business Logic Analysis: Deep understanding of DeFi protocols, governance mechanisms, and tokenomics
  • Intelligent Vulnerability Discovery: AI-assisted complex vulnerability pattern recognition

๐Ÿ” Comprehensive Security Detection System

  • Precision Vulnerability Detection: Focus on core languages for more accurate vulnerability identification
  • Cross-Contract Deep Analysis: Multi-contract interaction analysis and complex dependency tracking
  • Business Scenario Review: Professional security analysis for different DeFi scenarios
  • Intelligent False Positive Filtering: AI-assisted reduction of false positives, improving analysis accuracy

๐Ÿ›  Precision Language Architecture

  • Core Language Focus: Specialized framework for Solidity/Rust/C++/Move languages
  • Modular Design: Planning, validation, context, and analysis modules
  • Tree-sitter Parsing: Advanced parsing supporting core languages with high precision

๐Ÿ“ Project Structure

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

๐Ÿš€ Quick Start

Prerequisites

  • Python 3.10+
  • PostgreSQL 13+ (required for storing analysis results)
  • AI API Keys (supports OpenAI, Claude, DeepSeek, and other compatible services)

Installation

# 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
# Edit .env file with your API keys and database configuration

# 4. Initialize database
psql -U postgres -d postgres -f project_task.sql

# 5. Configure project dataset
# Edit src/dataset/agent-v1-c4/datasets.json to add your project configuration

# 6. Run analysis
python src/main.py

๐Ÿ“Š Usage Guide

Database Initialization

Initialize PostgreSQL database using the provided SQL file:

# Connect to PostgreSQL database
psql -U postgres -d postgres

# Execute SQL file to create table structure
\i project_task.sql

# Or use command line directly
psql -U postgres -d postgres -f project_task.sql

Project Configuration

Configure your project in 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
  }
}

Running Analysis

  1. Set Project ID: Configure your project ID in src/main.py
project_id = 'your_project_id'
  1. Execute Analysis:
python src/main.py
  1. View Results:
    • Detailed analysis records in database
    • output.xlsx report file
    • Mermaid business flow diagrams (if enabled)

๐Ÿ”ง Configuration

Quick Configuration

  1. Copy environment template:

    cp env.example .env
  2. Edit .env file with your API keys and preferences

Core Environment Variables

# Database Configuration (Required)
DATABASE_URL=postgresql://postgres:[email protected]:5432/postgres

# AI Model Configuration (Required)
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
ENABLE_DIALOGUE_MODE=False              # Whether to enable dialogue mode
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

๐Ÿ“ Complete Configuration: See env.example file for all configurable options and detailed descriptions

AI Model Configuration Details

Based on actual configuration in src/openai_api/model_config.json:

WARNING must set the model name based on your llm hub! WARNING must set the model name based on your llm hub! WARNING like in openrouter, sonnet 4 need to set to 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"
}

Recommended Configuration Schemes

๐Ÿš€ Quick Start (Small projects < 50 files)

SCAN_MODE=PURE_SCAN
COMPLEXITY_ANALYSIS_ENABLED=False
MAX_THREADS_OF_SCAN=3
BUSINESS_FLOW_COUNT=2

๐Ÿข Enterprise (Large projects > 100 files)

SCAN_MODE=COMMON_PROJECT_FINE_GRAINED
COMPLEXITY_ANALYSIS_ENABLED=True
MAX_THREADS_OF_SCAN=8
MAX_THREADS_OF_CONFIRMATION=30
BUSINESS_FLOW_COUNT=4

๐Ÿ’ฐ Cost Optimized

SCAN_MODE=PURE_SCAN
BUSINESS_FLOW_COUNT=1
MAX_THREADS_OF_SCAN=3
MAX_THREADS_OF_CONFIRMATION=10
COMPLEXITY_ANALYSIS_ENABLED=False

๐ŸŽฏ Use Cases

Blockchain & Web3 Projects

  • Smart Contract Security: Solidity, Rust, Move contract analysis
  • DeFi Protocol Analysis: AMM, lending, governance mechanism review
  • Cross-Chain Applications: Bridge security, multi-chain deployment analysis
  • NFT & Gaming: Minting logic, marketplace integration security

Traditional Software Projects

  • Web3 Backend: Python/Node.js API security analysis
  • Blockchain Infrastructure: Go/C++ node and client security
  • Enterprise Applications: Java enterprise blockchain applications
  • System-Level Code: C/C++ core components and TEE projects

Multi-Language Project Analysis

  • Polyglot Codebases: Cross-language dependency analysis
  • Microservice Architecture: Multi-service security assessment
  • Full-Stack Applications: Frontend, backend, and contract integration security

๐Ÿ“Š Analysis Reports

The platform generates comprehensive analysis reports including:

  • Security Vulnerability Report: Detailed vulnerability findings with severity ratings
  • Business Flow Diagrams: Visual representation of contract interactions
  • Gas Optimization Suggestions: Performance improvement recommendations
  • Best Practice Compliance: Adherence to security standards and guidelines

๐Ÿงช Testing

Run the test suite:

# Unit tests
python -m pytest tests/

# Integration tests
python -m pytest tests/integration/

# Coverage report
python -m pytest --cov=src tests/

๐Ÿค Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

๐Ÿ“„ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

๐Ÿ™ Acknowledgments

  • ANTLR4: For Solidity parsing capabilities
  • Claude AI: For advanced code understanding
  • Mermaid: For business flow visualization
  • OpenAI: For AI-powered analysis capabilities

๐Ÿ“ž Contact


๐Ÿ†• v2.0 Release Notes

Major Upgrades

  • Core Language Specialization: Focus on Solidity/Rust/C++/Move for optimal analysis experience
  • RAG Architecture Revolution: LanceDB merged 2-table architecture with 300% performance improvement
  • Intelligent Embedding: Multi-dimensional code understanding with significantly enhanced analysis precision
  • Architecture Optimization: 50% memory reduction, supporting larger-scale projects

Migration Guide

  • v2.0 is fully backward compatible, no configuration changes required
  • Unsupported language files will be automatically skipped without affecting system operation
  • Recommended to update configuration files for optimal performance experience

๐ŸŽ‰ Finite Monkey Engine v2.0 - Making Code Security Analysis More Intelligent, Professional, and Efficient!

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for finite-monkey-engine

Similar Open Source Tools

For similar tasks

For similar jobs