Clock Investigator

A blockchain forensics tool for tracking and analyzing cryptocurrency transactions, specifically focused on tracing funds related to hacks and suspicious activities.

Features

• Transaction flow tracking and visualization
• Pattern recognition for suspicious activities
• Real-time monitoring of addresses
• Telegram alerts for suspicious transactions
• Graph-based analysis using Neo4j
• Support for multiple blockchain networks

Prerequisites

• Python 3.8+
• Docker
• Neo4j (runs in Docker)
• Telegram Bot Token (for alerts)

Installation

1. Clone the repository:

git clone https://github.com/yourusername/ClockInvestigator.git
cd ClockInvestigator

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the package in development mode:

pip install -e .

4. Start the Neo4j database:

docker run -d --name neo4j \
    -p 7474:7474 -p 7687:7687 \
    -v neo4j_data:/data \
    -e NEO4J_AUTH=neo4j/ClockInvestigator2024! \
    -e NEO4J_ACCEPT_LICENSE_AGREEMENT=eval \
    -e NEO4J_apoc_export_file_enabled=true \
    -e NEO4J_apoc_import_file_enabled=true \
    -e NEO4J_apoc_import_file_use__neo4j__config=true \
    -e NEO4J_PLUGINS='["apoc", "graph-data-science"]' \
    neo4j:5.13.0-enterprise

5. Initialize the database schema:

./database/restore.sh

Configuration

1. Create a .env file in the project root:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=ClockInvestigator2024!
TELEGRAM_BOT_TOKEN=your_telegram_bot_token

2. Replace your_telegram_bot_token with your actual Telegram bot token.

Database Management

Backup

To create a backup of the current database state:

./database/backup.sh

Backups are stored in database/backups/ with timestamps.

Restore

To restore the database to its initial state:

./database/restore.sh

Project Structure

ClockInvestigator/
├── src/                    # Source code
│   ├── blockchain/         # Blockchain interaction modules
│   ├── analysis/          # Analysis and pattern recognition
│   ├── visualization/     # Graph visualization
│   └── alerts/           # Telegram alert system
├── database/              # Database management
│   ├── schemas/          # Neo4j schema definitions
│   ├── backups/         # Database backups
│   ├── backup.sh        # Backup script
│   └── restore.sh       # Restore script
├── tests/                # Test files
└── setup.py             # Package configuration

Usage

1. Access the Neo4j browser at http://localhost:7474 to view and query the graph database.
2. Use the Python API to:
   • Track transactions
   • Analyze patterns
   • Set up monitoring
   • Receive alerts

Development

1. Install development dependencies:

pip install -e ".[dev]"

2. Run tests:

pytest

Security Notes

• Keep your .env file secure and never commit it to version control
• Regularly update dependencies for security patches
• Monitor system logs for suspicious activities
• Backup your database regularly

License

MIT