Synapse Security Agents

An advanced framework for detecting smart contract vulnerabilities through reasoning-augmented Large Language Models (LLMs).

Overview

Synapse Security Agents is a sophisticated, AI-powered system designed to identify vulnerabilities in smart contracts. By leveraging state-of-the-art large language models and advanced reasoning techniques, Synapse Security Agents can detect a wide range of security flaws that might be overlooked by traditional static analysis tools.

The system employs a multi-agent architecture that breaks down the complex task of vulnerability detection into specialized phases, allowing for deeper analysis and more accurate results.

Key Features

• Multi-Agent Architecture: Specialized agents work together to analyze different aspects of smart contracts
• Advanced Preprocessing: Extracts and classifies functions to focus analysis on vital components
• Business Logic Flow Analysis: Understands the logical flow of contract operations to identify potential security issues
• Checklist-Based Detection: Systematically checks for known vulnerability patterns
• LLM-Enhanced Reasoning: Uses large language models to perform sophisticated analysis of code behavior
• Caching Layer: Optimizes performance by caching analysis results
• Comprehensive Reporting: Generates detailed reports of detected vulnerabilities in multiple formats

Supported Vulnerability Types

The system can detect various types of smart contract vulnerabilities, including:

• Reentrancy attacks
• Integer overflow/underflow
• Rounding issues
• Uninitialized variables
• Access control problems
• Front-running vulnerabilities
• And many more (see agents/detection_core/checklist.json for a full list)

System Architecture

The system follows a multi-phase approach to vulnerability detection:

1. Contract Preprocessing: Extracts and classifies functions from smart contracts
2. Logic Flow Analysis: Understands the business logic and data flow in each function
3. Vulnerability Detection: Analyzes code for potential vulnerabilities using specialized detection agents
4. Report Generation: Creates detailed reports of findings with explanations and severity ratings

Installation

Prerequisites

• Python 3.8+
• Access to LLM APIs (OpenAI, Deepseek, Mistral, etc.)

Setup

1. Clone the repository:

   git clone https://github.com/ret2happy/synapse_agents.git
   cd synapse_security_agents

2. Install the required dependencies:

   pip install -r requirements.txt

3. Configure your LLM access by editing config.toml with your API keys and preferences.

Usage

Basic Usage

Run the scanner on a smart contract project:

python main.py --project-dir path/to/smart_contract_project --output-dir scanning_output

Command Line Options

• --project-dir: Path to the project directory to analyze
• --project-id: Path to the project ID to analyze (with aid of website_project_meta.json)
• --output-dir: Directory for output reports (default: 'scanning_output')
• --enable-cache-layer: Enable caching of analysis results
• -v, --verbose: Enable verbose debug logging
• --config-file: Path to the configuration file (default: 'config.toml')

Configuration

The config.toml file contains various configuration profiles for different LLM backends. You can select the model to use by setting the CANDIDATE_PROFILE in the [main] section.

Example Output

The system generates comprehensive vulnerability reports in both Markdown and JSON formats. Reports include:

• Contract overview
• Detected vulnerabilities with detailed explanations
• Code snippets highlighting problematic areas
• Severity ratings
• Recommended fixes

Advanced Features

Cache Layer

Enable the cache layer to improve performance on repeated analyses:

python main.py --project-dir path/to/smart_contract_project --enable-cache-layer

Custom Model Selection

Modify the config.toml file to use different LLM backends:

[main]
CANDIDATE_PROFILE = "deepseek-r1"  # Change to your preferred model

Project Structure

• agents/: Core agents for contract analysis and vulnerability detection
  • detection_core/: Vulnerability detection logic
  • phases/: Different phases of analysis
  • cluster_knowledge/: Knowledge base for different vulnerability types
• common_utils/: Shared utilities and helpers

License

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