Architecture Overview

This document provides a comprehensive overview of the Deceptgold system architecture, explaining how components interact to transform cyber attacks into valuable digital assets.

System Overview
Core Components
Data Flow
Smart Contract Architecture
Security Design
Technology Stack
Deployment Architecture

System Overview

Deceptgold is a next-generation cybersecurity platform that monetizes cyber attacks through a sophisticated deception and tokenization system.

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Deceptgold System                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐   │
│  │   Honeypot   │────▶ │  Signature   │────▶ |  Blockchain  │   |
│  │    System    │      │  Validation  │      │  Integration │   │
│  │ (OpenCanary) │      │   (ECDSA)    │      │   (Web3)     │   │
│  └──────────────┘      └──────────────┘      └──────────────┘   │
│         │                      │                      │         │
│         ▼                      ▼                      ▼         │
│  ┌──────────────┐      ┌──────────────┐      ┌──────────────┐   │
│  │   Attack     │      │    Crypto    │      │    Token     │   │
│  │   Logging    │      │   Signing    │      │   Minting    │   │
│  └──────────────┘      └──────────────┘      └──────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Principles

Deception-First: Deploy realistic honeypots to attract attackers
Cryptographic Integrity: Every attack is cryptographically signed
Blockchain Validation: Smart contracts verify and tokenize attacks
Anti-Farming: Multiple mechanisms prevent self-farming
Privacy-Preserving: User data is anonymized and protected

Core Components

1. CLI Application Layer

Technology: Cyclopts (Python CLI framework)

Purpose: User interface for all system operations

Key Files:

src/deceptgold/__main__.py - Application entry point
src/deceptgold/commands/ - Command implementations

Commands:

deceptgold
├── user              # User management
│   ├── create        # Create new user account
│   ├── wallet        # Manage crypto wallet
│   └── config        # User configuration
├── service           # Service control
│   ├── start         # Start honeypot service
│   ├── stop          # Stop honeypot service
│   └── status        # Check service status
└── notify            # Notifications
    ├── telemetry     # Send telemetry data
    └── alerts        # Configure alerts

Architecture:

# Application initialization flow
init_app()
  ├─ Load configuration
  ├─ Initialize logging
  ├─ Register commands (user, service, notify)
  ├─ Execute telemetry
  └─ Run CLI application

2. Honeypot System

Technology: OpenCanary (customized)

Purpose: Attract and log attack attempts

Key Files:

src/deceptgold/helper/opencanary/ - Honeypot implementation
src/deceptgold/helper/opencanary/proxy_logger.py - Custom logging

Supported Services:

SSH (port 22)
HTTP/HTTPS (ports 80/443)
FTP (port 21)
MySQL (port 3306)
SMB (port 445)
And more...

Attack Detection Flow:

Attacker → Honeypot Service → Attack Detected → Log Entry Created
                                                        ↓
                                                 Signature Added
                                                        ↓
                                                 Validation Queue

Log Format:

{
  "timestamp": "2025-12-22T19:58:22Z",
  "source_ip": "192.168.1.100",
  "service": "ssh",
  "attack_type": "brute_force",
  "requests_count": 1500,
  "fingerprint": "system_unique_id",
  "signature": "0x..."
}

3. Cryptographic Signature System

Technology: ECDSA (Elliptic Curve Digital Signature Algorithm)

Purpose: Ensure attack logs are authentic and tamper-proof

Key Files:

src/deceptgold/helper/signature.py - Signature generation/validation

Process:

Attack Log Creation:

attack_data = {
    "timestamp": current_time,
    "source_ip": attacker_ip,
    "service": "ssh",
    "requests": 1500
}

Serialization:

message = json.dumps(attack_data, sort_keys=True)

Hashing (Keccak-256):

message_hash = keccak_256(message.encode())

Signing (ECDSA):

signature = private_key.sign(message_hash)

Verification (on-chain):

function verifySignature(
    bytes32 messageHash,
    bytes memory signature
) public view returns (bool) {
    address signer = ecrecover(messageHash, signature);
    return signer == authorizedSigner;
}

Security Properties:

Authenticity: Only Deceptgold instances can sign logs
Integrity: Any tampering invalidates the signature
Non-repudiation: Signatures prove origin
Privacy: Private key is obfuscated in compiled code

4. Blockchain Integration

Technology: Web3.py, Ethereum-compatible networks

Purpose: Tokenize verified attacks on-chain

Key Files:

src/deceptgold/helper/blockchain/ - Web3 integration

Supported Networks:

Ethereum Mainnet
Polygon
Binance Smart Chain
Testnets (Sepolia, Mumbai, etc.)

Smart Contract Interaction:

from web3 import Web3

# Connect to network
w3 = Web3(Web3.HTTPProvider(rpc_url))

# Load contract
contract = w3.eth.contract(
    address=contract_address,
    abi=contract_abi
)

# Submit attack for tokenization
tx = contract.functions.mintTokens(
    attack_hash,
    signature,
    reward_amount
).build_transaction({
    'from': user_address,
    'nonce': w3.eth.get_transaction_count(user_address)
})

# Sign and send
signed_tx = w3.eth.account.sign_transaction(tx, private_key)
tx_hash = w3.eth.send_raw_transaction(signed_tx.rawTransaction)

5. Fingerprinting and Anti-Farming

Technology: Custom system identification

Purpose: Prevent users from farming their own tokens

Key Files:

src/deceptgold/helper/fingerprint.py - System fingerprinting

Mechanisms:

System Fingerprinting:
- Hardware identifiers (MAC address, CPU ID)
- System configuration hash
- Installation timestamp
- Geographic location (optional)
Rate Limiting:
- Maximum requests per IP per hour
- Maximum tokens per system per day
- Cooldown periods between claims
Behavioral Analysis:
- Attack pattern recognition
- Timing analysis (too regular = suspicious)
- Source diversity requirements
On-Chain Validation:
- Smart contract checks fingerprint uniqueness
- Rejects duplicate or suspicious patterns

Anti-Farming Flow:

Attack Log → Fingerprint Check → Rate Limit Check → Pattern Analysis
                ↓                      ↓                    ↓
            Unique?              Within Limits?        Natural Pattern?
                ↓                      ↓                    ↓
                └──────────────────────┴────────────────────┘
                                       ↓
                              Valid or Rejected

6. Configuration Management

Key Files:

src/deceptgold/configuration/ - Config management
src/deceptgold/resources/config/ - Config templates

Configuration Hierarchy:

System Defaults
    ↓
User Configuration (~/.deceptgold/config.json)
    ↓
Environment Variables
    ↓
Command-Line Arguments

Key Settings:

Blockchain network and RPC endpoint
Honeypot services to enable
Logging verbosity and retention
Wallet configuration
Telemetry preferences

Data Flow

End-to-End Attack Processing

┌─────────────┐
│   Attacker  │
└──────┬──────┘
       │ 1. Attack Attempt
       ▼
┌─────────────────────┐
│  Honeypot Service   │
│   (OpenCanary)      │
└──────┬──────────────┘
       │ 2. Log Attack
       ▼
┌─────────────────────┐
│   Attack Logger     │
│  (Custom Handler)   │
└──────┬──────────────┘
       │ 3. Create Log Entry
       ▼
┌─────────────────────┐
│ Fingerprint System  │
│  (Anti-Farming)     │
└──────┬──────────────┘
       │ 4. Add System ID
       ▼
┌─────────────────────┐
│  Signature Module   │
│      (ECDSA)        │
└──────┬──────────────┘
       │ 5. Sign Log
       ▼
┌─────────────────────┐
│   Local Storage     │
│  (Queue for TX)     │
└──────┬──────────────┘
       │ 6. Batch Ready
       ▼
┌─────────────────────┐
│  Blockchain Client  │
│      (Web3)         │
└──────┬──────────────┘
       │ 7. Submit Transaction
       ▼
┌─────────────────────┐
│  Smart Contract     │
│  (Validation)       │
└──────┬──────────────┘
       │ 8. Verify Signature
       ▼
┌─────────────────────┐
│  Smart Contract     │
│   (Minting)         │
└──────┬──────────────┘
       │ 9. Mint Tokens
       ▼
┌─────────────────────┐
│   User Wallet       │
│  (ERC-20 Tokens)    │
└─────────────────────┘

Data Persistence

Local Storage:

Attack logs: /var/log/deceptgold/attacks.log
Configuration: ~/.deceptgold/config.json
Wallet keystore: ~/.deceptgold/keystore/
Pending transactions: ~/.deceptgold/queue/

Blockchain Storage:

Token balances: ERC-20 contract state
Attack hashes: Validation contract storage
Signature records: Immutable on-chain logs

Smart Contract Architecture

Dual Contract System

Deceptgold uses two smart contracts for security and modularity:

1. Token Contract (ERC-20)

Purpose: Manage token supply and transfers

Key Functions:

contract DeceptgoldToken is ERC20 {
    address public minter;
    
    function mint(address to, uint256 amount) external {
        require(msg.sender == minter, "Only minter");
        _mint(to, amount);
    }
    
    function burn(uint256 amount) external {
        _burn(msg.sender, amount);
    }
}

Features:

Standard ERC-20 implementation
Controlled minting (only validation contract can mint)
Burnable for utility consumption
Transfer restrictions (optional)

2. Validation Contract

Purpose: Verify attack signatures and authorize minting

Key Functions:

contract AttackValidator {
    address public authorizedSigner;
    mapping(bytes32 => bool) public processedAttacks;
    DeceptgoldToken public token;
    
    function validateAndMint(
        bytes32 attackHash,
        bytes memory signature,
        address recipient,
        uint256 reward
    ) external {
        // 1. Verify signature
        require(
            verifySignature(attackHash, signature),
            "Invalid signature"
        );
        
        // 2. Check not already processed
        require(
            !processedAttacks[attackHash],
            "Already processed"
        );
        
        // 3. Mark as processed
        processedAttacks[attackHash] = true;
        
        // 4. Mint tokens
        token.mint(recipient, reward);
        
        emit AttackTokenized(attackHash, recipient, reward);
    }
    
    function verifySignature(
        bytes32 messageHash,
        bytes memory signature
    ) internal view returns (bool) {
        address signer = ecrecover(messageHash, signature);
        return signer == authorizedSigner;
    }
}

Security Features:

Signature verification (ecrecover)
Replay protection (processedAttacks mapping)
Single authorized signer
Event logging for transparency

Token Economics

Reward Calculation:

Token Reward = f(attack_type, requests_count, ip_diversity, service_value)

Example:
- SSH brute force (1000 requests) = 10 tokens
- DDoS attempt (1M requests) = 1000 tokens
- Multi-service attack = bonus multiplier

See documentation/reward_calculation_specification.md for details.

Security Design

Multi-Layer Security

Code Obfuscation (PyArmor)
- Protects private key embedded in code
- Prevents reverse engineering
- Platform-specific compilation
Cryptographic Signing (ECDSA)
- Every attack log is signed
- Signatures verified on-chain
- Keccak-256 hashing
Anti-Farming Mechanisms
- System fingerprinting
- Rate limiting
- Behavioral analysis
- On-chain duplicate detection
Smart Contract Security
- Replay protection
- Access control
- Event logging
- Upgradeable design (optional)

Threat Model

Protected Against:

✅ Self-farming (fingerprinting + rate limits)
✅ Log tampering (cryptographic signatures)
✅ Replay attacks (on-chain tracking)
✅ Unauthorized minting (signature verification)
✅ Private key extraction (code obfuscation)

Potential Risks:

⚠️ Sophisticated reverse engineering (mitigated by obfuscation)
⚠️ Distributed self-farming (mitigated by behavioral analysis)
⚠️ Smart contract vulnerabilities (mitigated by audits)

Technology Stack

Core Technologies

Component	Technology	Purpose
Language	Python 3.11+	Core implementation
CLI Framework	Cyclopts	Command-line interface
Honeypot	OpenCanary	Attack detection
Blockchain	Web3.py	Ethereum interaction
Cryptography	ecdsa, eth-account	Signature generation
Packaging	Briefcase	Multi-platform builds
Obfuscation	PyArmor	Code protection
Dependency Mgmt	Poetry	Python packages

Key Dependencies

[tool.poetry.dependencies]
python = "^3.11"
cyclopts = "^3.11.1"        # CLI framework
opencanary = "^0.9.5"       # Honeypot system
web3 = "^7.11.1"            # Blockchain integration
ecdsa = "^0.19.1"           # Cryptographic signing
eth-account = "^0.13.7"     # Ethereum accounts
qrcode-terminal = "^0.8"    # QR code display
briefcase = "^0.3.22"       # Application packaging
pyarmor = "^9.1.6"          # Code obfuscation

Deployment Architecture

Deployment Models

1. On-Premises Deployment

Enterprise Network
├── DMZ
│   └── Deceptgold Honeypots (multiple instances)
├── Internal Network
│   └── Deceptgold Management Server
└── Blockchain Connection
    └── RPC Node (self-hosted or provider)

2. Cloud Deployment

Cloud Provider (AWS/GCP/Azure)
├── VPC
│   ├── Public Subnet
│   │   └── Honeypot Instances (auto-scaling)
│   └── Private Subnet
│       └── Management & Logging
└── Blockchain
    └── Managed RPC (Infura/Alchemy)

3. Hybrid Deployment

On-Premises Honeypots ─┐
Cloud Honeypots ────────┼─→ Centralized Logging ─→ Blockchain
Edge Honeypots ─────────┘

Scalability Considerations

Horizontal Scaling:

Deploy multiple honeypot instances
Each instance has unique fingerprint
Centralized log aggregation
Batch transaction submission

Performance:

Async attack logging
Transaction batching (reduce gas costs)
Local queue for offline resilience
Efficient signature generation

Monitoring and Observability

Metrics:

Attacks detected per hour
Tokens minted per day
Service uptime
Blockchain transaction status

Logging:

Attack logs (structured JSON)
Application logs (errors, warnings)
Blockchain transaction logs
Telemetry data (optional)

Alerts:

Service downtime
Blockchain connection issues
Suspicious farming patterns
Low token balance (for gas)

Future Architecture Enhancements

Planned Improvements

Distributed Architecture
- Peer-to-peer attack sharing
- Decentralized validation
- Cross-organization intelligence
Advanced Analytics
- Machine learning for attack classification
- Predictive threat modeling
- Automated response recommendations
Multi-Chain Support
- Layer 2 solutions (Arbitrum, Optimism)
- Cross-chain bridges
- Multi-token rewards
Enhanced Privacy
- Zero-knowledge proofs for validation
- Confidential transactions
- Anonymous attack reporting

References

DEVELOPMENT.md - Development setup and workflow
CONTRIBUTING.md - Contribution guidelines
documentation/whitepaper.md - Project vision
ERC-20 Standard
OpenCanary Documentation

Questions or suggestions? Contact: contact@decept.gold

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Architecture Overview

Table of Contents

System Overview

High-Level Architecture

Key Principles

Core Components

1. CLI Application Layer

2. Honeypot System

3. Cryptographic Signature System

4. Blockchain Integration

5. Fingerprinting and Anti-Farming

6. Configuration Management

Data Flow

End-to-End Attack Processing

Data Persistence

Smart Contract Architecture

Dual Contract System

1. Token Contract (ERC-20)

2. Validation Contract

Token Economics

Security Design

Multi-Layer Security

Threat Model

Technology Stack

Core Technologies

Key Dependencies

Deployment Architecture

Deployment Models

1. On-Premises Deployment

2. Cloud Deployment

3. Hybrid Deployment

Scalability Considerations

Monitoring and Observability

Future Architecture Enhancements

Planned Improvements

References

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History

ARCHITECTURE.md

File metadata and controls

Architecture Overview

Table of Contents

System Overview

High-Level Architecture

Key Principles

Core Components

1. CLI Application Layer

2. Honeypot System

3. Cryptographic Signature System

4. Blockchain Integration

5. Fingerprinting and Anti-Farming

6. Configuration Management

Data Flow

End-to-End Attack Processing

Data Persistence

Smart Contract Architecture

Dual Contract System

1. Token Contract (ERC-20)

2. Validation Contract

Token Economics

Security Design

Multi-Layer Security

Threat Model

Technology Stack

Core Technologies

Key Dependencies

Deployment Architecture

Deployment Models

1. On-Premises Deployment

2. Cloud Deployment

3. Hybrid Deployment

Scalability Considerations

Monitoring and Observability

Future Architecture Enhancements

Planned Improvements

References