🍯 HoneyCloud

Next-Generation AI-Powered Honeypot & SOC Intelligence Platform

Deceive. Detect. Defend.

---

📑 Table of Contents

1. Executive Summary
2. Core Capabilities & Features
3. System Architecture
4. Technology Stack
5. Directory Structure & Module Breakdown
6. Prerequisites & System Requirements
7. Installation & Setup Guide
8. Configuration & Environment Variables
9. Database Schema & Models
10. RESTful API Documentation
11. Machine Learning & Deep Learning
12. Automated Investigations & Threat Hunting
13. Advanced Analytics & BI
14. Deception Environment & Shadow Nodes
15. Alerting & Notification System
16. Frontend Architecture & Components
17. Deployment Guide (Render, Docker, AWS)
18. Security & Compliance
19. Troubleshooting & FAQ
20. Contributing
21. License

---

1. 🚀 Executive Summary

HoneyCloud is a state-of-the-art, production-ready honeypot orchestration and Security Operations Center (SOC) intelligence platform. Designed to seamlessly mimic vulnerable enterprise infrastructure, HoneyCloud attracts malicious actors, traps them in heavily monitored deception environments, and leverages advanced Machine Learning (ML) algorithms to classify their behavior in real-time.

By acting as a decoy, HoneyCloud shifts the asymmetrical advantage back to the defenders. It safely logs zero-day exploits, brute-force attempts, unauthorized access, and malicious payloads without exposing the actual production network.

Why HoneyCloud?

• Proactive Defense: Don't wait for attackers to hit your real servers. Lure them into HoneyCloud.
• High-Fidelity Intelligence: Every alert generated by HoneyCloud is a guaranteed threat, eliminating alert fatigue.
• Automated Threat Modeling: Real-time ML models map attacks to the MITRE ATT&CK framework automatically.
• Enterprise Reporting: Generate beautiful, SOC-compliant PDF, CSV, and Excel reports instantly.

---

2. ✨ Core Capabilities & Features

🎯 Deception & Decoy Systems

• Shadow Nodes: Deploy lightweight, high-interaction decoy nodes across multiple geographic regions.
• Protocol Emulation: Emulate SSH, FTP, HTTP, HTTPS, MySQL, Redis, and custom proprietary protocols.
• Vulnerability Simulation: Purposefully expose mock vulnerabilities (e.g., Log4j, outdated Apache) to attract specific threat actors.

🧠 AI-Powered Threat Analysis & Deep Learning

• Behavioral ML Engine: Uses Random Forest and Isolation Forest to classify attacks as benign, anomaly, or malicious.
• Deep Learning Engine: Advanced neural network architectures for robust threat detection and anomaly classification.
• Dynamic Risk Scoring: Calculates threat severity (0-100) based on payload toxicity, IP reputation, and attack velocity.
• Automated Labeling: Automatically labels incoming payloads using Natural Language Processing (NLP) techniques.

📊 Comprehensive SOC Dashboard & Advanced Analytics

• Real-Time Telemetry: Live WebSockets stream attack data directly to a React-based interactive dashboard.
• Global Threat Map: Visualize the geographical origin of attacks using integrated GeoIP databases.
• Attack Timelines & Investigations: Scroll through chronological timelines of attacker movements and perform deep automated investigations.
• Advanced Metrics: Extensive data modeling, trend analysis, and database optimization for rapid querying.

🏢 SaaS & Multi-Tenant Architecture

• Subscription Management: Full support for multi-tenant SaaS platforms with automated billing and subscription tiers.
• Production Optimized: Advanced deployment optimizers and database partitioning for high availability.

🔔 Multi-Channel Alerting

• Telegram Bot Integration: Receive instant push notifications to your mobile device for HIGH and CRITICAL alerts.
• Email Dispatcher: Automated email alerts powered by Resend API.
• Custom Webhooks: Forward events to Splunk, Datadog, or your internal SIEM.

📑 Automated Reporting & Data Management

• PDF Generation: Create visually stunning, SOC-ready PDF incident reports utilizing ReportLab.
• Excel & CSV Exports: Download raw data for data science and offline analysis.
• Recycle Bin Management: Safely soft-delete and manage historical event logs without breaking audit trails.

---

3. 🏗️ System Architecture

HoneyCloud is built on a modern, decoupled microservices architecture.

High-Level Flow

1. Attacker probes the exposed IP address.
2. Deception Routers (Shadow Nodes) intercept the traffic.
3. Traffic is forwarded to the FastAPI Backend.
4. The ML Engine analyzes the payload and assigns a Threat Score.
5. The Database (SQLite/PostgreSQL) stores the immutable attack log.
6. The Alert System triggers Telegram/Email notifications.
7. The React Frontend pulls the data for SOC analysts.

Component Diagram

[ Attacker ]
     |
     v
[ Reverse Proxy / Load Balancer ]
     |
     +---> [ Shadow Node (SSH Decoy) ]
     |
     +---> [ Shadow Node (HTTP Decoy) ]
     |
     v
[ FastAPI Backend (Core API) ] <---> [ ML Threat Engine (Scikit-Learn) ]
     |
     +---> [ Database (SQLite/PG) ]
     |
     +---> [ Notification Service (Telegram/Email) ]
     |
     v
[ React SOC Dashboard ]

---

4. 🛠️ Technology Stack

Frontend

• Framework: React 18
• Build Tool: Vite
• Styling: Tailwind CSS (Vanilla CSS fallbacks available)
• Icons: Lucide React
• Routing: React Router DOM
• Charts: Recharts

Backend

• Framework: FastAPI (Python 3.10+)
• Server: Uvicorn / Gunicorn
• Database ORM: SQLAlchemy
• Authentication: JWT (JSON Web Tokens)
• Machine Learning: Scikit-Learn, Pandas, NumPy
• Report Generation: ReportLab (PDF), OpenPyXL (Excel)
• Background Tasks: Celery / Asyncio
• Geolocation: GeoIP2

---

5. 📂 Directory Structure & Module Breakdown

The repository is divided into two primary directories: backend and frontend.

HoneyCloud-X/
├── backend/
│   ├── app/
│   │   ├── api/                # API Routing & Controllers
│   │   │   ├── routes/
│   │   │   │   ├── alerts.py   # Alert configuration endpoints
│   │   │   │   ├── auth.py     # Login, JWT, User Management
│   │   │   │   ├── enhancements.py # SaaS and advanced analytics features
│   │   │   │   ├── events.py   # Attack event ingestion
│   │   │   │   ├── health.py   # Infrastructure health checks
│   │   │   │   ├── investigation.py # Attack investigations
│   │   │   │   ├── ml.py       # ML engine operations
│   │   │   │   ├── recycle_bin.py # Event soft delete management
│   │   │   │   ├── reports.py  # PDF/Excel/CSV Generation
│   │   │   │   ├── shadow_nodes.py # Deception nodes management
│   │   │   │   └── telegram.py # Telegram Bot integration
│   │   ├── core/               # Core configuration and security
│   │   ├── deception_engine/   # Threat deception processing
│   │   ├── deception_env/      # Emulated vulnerability environments
│   │   ├── investigation_engine/ # Automated event investigations
│   │   ├── services/           # Business logic
│   │   ├── tasks/              # Background workers (Celery/Async)
│   │   ├── advanced_analytics.py # Advanced metrics and statistics
│   │   ├── advanced_security.py # Security hardening
│   │   ├── alert_system.py     # Event-driven alert dispatcher
│   │   ├── database_optimizer.py # Database performance tuning
│   │   ├── deep_learning_engine.py # Advanced AI/ML threat detection
│   │   ├── init_saas.py        # SaaS environment initialization
│   │   ├── main.py             # FastAPI Application Factory
│   │   ├── ml_engine.py        # Core Machine Learning pipeline
│   │   ├── models.py           # SQLAlchemy Database Models
│   │   ├── production_optimizer.py # Production deployment optimizers
│   │   ├── saas_api.py         # SaaS subscription logic
│   │   ├── schemas.py          # Pydantic Validation Schemas
│   │   ├── stream_processor.py # Real-time event streaming
│   │   ├── subscription_manager.py # Tenant management
│   │   ├── threat_intelligence.py # Threat enrichment
│   ├── requirements.txt        # Python dependencies
│   └── honeycloud.db           # SQLite Database (Auto-generated)
│
├── frontend/
│   ├── src/
│   │   ├── components/         # Reusable React UI Components
│   │   │   ├── Navbar.jsx
│   │   │   ├── ParticlesBackground.jsx
│   │   │   └── Sidebar.jsx
│   │   ├── pages/              # Main Route Views
│   │   │   ├── AttackDetails.jsx # Granular attack data
│   │   │   ├── Dashboard.jsx   # Primary SOC View
│   │   │   ├── Investigations.jsx # Investigation tracking
│   │   │   ├── Login.jsx       # Authentication Portal
│   │   │   ├── RecycleBin.jsx  # Deleted events manager
│   │   │   ├── Reports.jsx     # Report Generation UI
│   │   │   └── Settings.jsx    # System Configuration
│   │   ├── context/            # React Context Providers
│   │   ├── App.jsx             # Root React Component
│   │   └── main.jsx            # React DOM Entry
│   ├── package.json            # Node dependencies
│   ├── tailwind.config.js      # Tailwind configuration
│   └── vite.config.js          # Vite configuration

---

6. ⚙️ Prerequisites & System Requirements

To run HoneyCloud successfully, ensure your environment meets the following specifications:

Minimum Hardware

• CPU: 2 Cores (4+ recommended for ML processing)
• RAM: 2 GB (4 GB recommended)
• Storage: 10 GB SSD

Software Requirements

• OS: Linux (Ubuntu/Debian preferred), macOS, or Windows 10/11
• Python: Python 3.9, 3.10, or 3.11
• Node.js: Node 18.x or higher
• Package Managers: pip and npm

---

7. 🚀 Installation & Setup Guide

Step 1: Clone the Repository

git clone https://github.com/YourOrg/HoneyCloud-X.git
cd HoneyCloud-X

Step 2: Backend Setup

1. Navigate to the backend directory:

   cd backend

2. Create and activate a Python Virtual Environment:

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

3. Install Python dependencies:

   pip install -r requirements.txt

   (Note: For Render/Cloud deployment, heavy ML libraries like TensorFlow are excluded by default to prevent OOM errors).
4. Start the FastAPI Server:

   python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Step 3: Frontend Setup

1. Open a new terminal and navigate to the frontend directory:

   cd frontend

2. Install Node dependencies:

   npm install

3. Start the Vite Development Server:

   npm run dev

4. Access the SOC Dashboard at http://localhost:5173.

---

8. 🔧 Configuration & Environment Variables

HoneyCloud uses .env files for secure configuration. Create a .env file in the backend/ directory.

Backend .env Reference

Variable	Type	Default	Description
APP_NAME	String	HoneyCloud	Name of the application
DEBUG	Boolean	False	Enable detailed traceback logs
DATABASE_URL	String	sqlite:///./honeycloud.db	Connection string for SQLAlchemy
JWT_SECRET_KEY	String	changeme	256-bit secret for JWT signing
JWT_EXPIRE_MINUTES	Integer	60	Token expiration time
TELEGRAM_BOT_TOKEN	String	None	Bot token provided by @BotFather
TELEGRAM_CHAT_ID	String	None	Chat ID for alert dispatch
EMAIL_ENABLED	Boolean	False	Enable Resend API email alerts
RESEND_API_KEY	String	None	Resend API Key
ALERT_EMAIL_TO	String	None	Destination email for alerts

---

9. 🗄️ Database Schema & Models

HoneyCloud utilizes a normalized relational database schema.

Table: organizations

Manages multi-tenant workspaces.

• id (PK, Integer)
• name (String, 255)
• plan (String, 50) - free, starter, pro, enterprise
• is_active (Boolean)

Table: users

Manages operator authentication.

• id (PK, Integer)
• username (String, 50)
• hashed_password (String, 255)
• role (String, 20) - admin, operator, viewer
• organization_id (FK, Integer)

Table: attack_events

The core ledger of all intercepted malicious activity.

• id (PK, Integer)
• timestamp (DateTime, UTC)
• source_ip (String, 45)
• service_name (String, 100) - e.g., SSH, HTTP
• method (String, 10) - e.g., GET, POST
• payload (Text) - Raw dump of attacker payload
• severity (String, 20) - LOW, MEDIUM, HIGH, CRITICAL
• threat_score (Float) - 0.0 to 100.0
• ai_label (String, 20) - benign, anomaly, malicious
• location (JSON) - GeoIP resolution data
• is_deleted (Boolean) - Soft delete flag

---

10. 🔌 RESTful API Documentation

FastAPI automatically generates interactive Swagger documentation. When the backend is running, visit: 👉 http://localhost:8000/docs

Key Endpoints

Authentication

• POST /api/auth/login
  • Authenticates user and returns an access token.
  • Payload: OAuth2PasswordRequestForm
  • Response: { "access_token": "ey...", "token_type": "bearer" }

Events

• GET /api/events
  • Retrieves paginated attack events.
  • Query Params: limit, offset, severity
• POST /api/events/simulate
  • Injects synthetic attack events for testing the SOC dashboard.

Reports

• GET /api/reports/generate
  • Generates comprehensive PDF, CSV, or Excel reports.
  • Query Params: format (pdf|csv|excel), limit (int)
  • Response: Download URL to the generated file.

Alerts

• POST /api/telegram/test
  • Sends a test alert to the configured Telegram chat.

---

11. 🧠 Machine Learning & Deep Learning

HoneyCloud does not rely purely on static signatures. It utilizes an embedded ML pipeline and an advanced Deep Learning engine to evaluate threats.

Threat Routing Engine

When an event arrives, the Threat Routing Engine analyzes it:

1. Feature Extraction: Extracts payload length, temporal features, service features, SQL injection keywords, script tags, and path traversal strings (../).
2. Model Inference: Passes features to a pre-trained RandomForestClassifier.
3. Anomaly Detection: Passes features to an IsolationForest to detect zero-day anomalies that don't match known signatures.
4. Scoring: Calculates a mathematical threat_score.
5. Severity Mapping:
   • 0 - 30: LOW
   • 30 - 60: MEDIUM
   • 60 - 80: HIGH
   • 80 - 100: CRITICAL

Deep Learning Capabilities

Our optional Deep Learning package (powered by TensorFlow) introduces:

• LSTM Networks: Recurrent neural networks (RNN) analyzing sequential attack events over time to detect multi-stage persistent threats.
• CNN 1D (Convolutional Neural Networks): Analyzes payload text as one-dimensional sequence data, extracting complex non-linear spatial features from HTTP payloads or SSH commands.
• Autoencoders: Neural networks trained purely on benign traffic to perfectly reconstruct it. When a zero-day payload arrives, the reconstruction error spikes, flagging it immediately.
• NLP Tokenization: Tokenizes payload sequences using the Tokenizer API for embedding layers.

Automated Retraining

The ml_trainer.py background service monitors the database. Every 24 hours (or upon accumulating 50+ new events), it automatically retrains the Scikit-Learn models using the latest empirical data to improve accuracy.

---

12. 🕵️ Automated Investigations & Threat Hunting

When complex attacks occur, HoneyCloud acts as an automated Level 1 SOC Analyst via the investigation_engine:

• Correlation Engine: Aggregates disjointed logs across HTTP, SSH, and MySQL mimicking that originate from the same subnet or display similar behavioral entropy.
• Timeline Analyzer: Builds a sequential graph of attacker actions, calculating the exact time delta between probing, exploiting, and post-exploitation behavior.
• Profile Builder: Automatically generates a comprehensive "Attacker Profile" linking known IPs, User-Agents, and TTPs to track repeat offenders across long timeframes.
• MITRE Mapper: Dynamically parses payload characteristics and maps them to MITRE ATT&CK Matrix techniques (e.g., T1595 Active Scanning, T1110 Brute Force).

---

13. 📈 Advanced Analytics & Business Intelligence

HoneyCloud provides rich, proactive analytics to forecast attacks before they scale.

• Predictive Forecasting: Uses time-series analysis on historical data (moving averages, rolling windows) to predict upcoming attack volumes.
• Trend Analysis: Identifies shifts in geographical origins, targeted services, and severity distributions over 7-day, 14-day, and 30-day windows.
• Actionable Insights: The system generates automated natural language insights, providing severity context, confidence scores, and specific remediation recommendations.
• Database Optimization: A background database_optimizer.py ensures all queries fueling these analytics remain highly performant, employing automatic indexing and query analysis.

---

14. 🕸️ Deception Environment & Shadow Nodes

The deception environment is the net that catches the attackers.

Emulated Services

• Web App Decoy (Port 80/443): Simulates a vulnerable eCommerce platform, logging SQL injection attempts and XSS probes.
• SSH Decoy (Port 22): Simulates an open SSH port. Captures brute-force credential stuffing attacks.
• Database Decoy (Port 3306): Simulates an exposed MySQL database to capture unauthorized connection attempts.

To enable external routing, point your domain or load balancer to the HoneyCloud server IP.

---

15. 📱 Alerting & Notification System

HoneyCloud ensures SOC analysts never miss a critical breach.

Telegram Integration

1. Message @BotFather on Telegram and create a new bot.
2. Obtain the HTTP API Token.
3. Add the bot to your SOC group chat and retrieve the Chat ID.
4. Update your .env:

   TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
   TELEGRAM_CHAT_ID=-1001234567890

Email Integration (Resend)

1. Sign up at Resend.com.
2. Generate an API Key.
3. Update your .env:

   EMAIL_ENABLED=true
   RESEND_API_KEY=re_123456789
   ALERT_EMAIL_TO=soc@yourcompany.com

---

16. 🎨 Frontend Architecture & Components

The frontend is a strictly typed React application emphasizing aesthetics, usability, and speed.

Design Philosophy

• Dark Mode First: Designed specifically for SOC analysts working in dark environments to reduce eye strain.
• Glassmorphism: Utilizes subtle blurs and transparencies to create a deep, layered UI.
• Micro-Animations: Employs Framer Motion / CSS transitions for smooth feedback.

Key Components

• <ThreatMap />: A D3/Leaflet component mapping source IPs geographically.
• <EventTable />: A high-performance data grid with sorting, filtering, and pagination.
• <ReportGenerator />: An intuitive modal allowing users to select PDF/Excel/CSV formats and define date ranges.

---

17. ☁️ Deployment Guide (Render, Docker, AWS)

Deploying to Render (Recommended for Free Tier)

1. Push your repository to GitHub.
2. Log in to Render and select New Web Service.
3. Connect your GitHub repository.
4. Build Command: pip install -r requirements.txt (Ensure heavy ML libs like TensorFlow are removed from requirements.txt for the free tier).
5. Start Command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
6. Add your Environment Variables.
7. Click Deploy.

Docker Deployment

(Dockerfile provided in repository)

docker build -t honeycloud .
docker run -p 8000:8000 --env-file .env honeycloud

---

18. 🛡️ Security & Compliance

• Data Isolation: Attack data is strictly segregated from configuration data.
• Immutable Logs: Attack events are designed to be append-only. Deletions are soft-deletes (is_deleted = True) to maintain audit trails.
• JWT Security: Tokens expire hourly and require strong signatures.
• MITRE ATT&CK: Alerts are mapped directly to MITRE tactics (e.g., T1595 - Active Scanning) to assist you in compliance reporting.

---

19. 🚑 Troubleshooting & FAQ

Q: Why does the PDF show 100/100 for all Risk Scores? A: Ensure you have restarted the backend after pulling the latest updates. The string matcher requires .strip() to successfully format risk scores.

Q: Render deployment is stuck on "Deploying" and timing out. A: Render's Free Tier has a 512MB RAM limit. If tensorflow or torch are in your requirements.txt, the server will OOM (Out of Memory) and crash silently. Remove them from requirements.txt; HoneyCloud will safely fall back to basic ML models.

Q: Why does the dashboard take 50 seconds to load sometimes? A: Cloud providers (like Render) spin down free instances after 15 minutes of inactivity. The 50-second delay is the server booting back up.

Q: How do I clear the Recycle Bin? A: Currently, items in the recycle bin are retained for audit purposes. You can permanently delete them by accessing the database directly or waiting for the 30-day auto-purge cycle.

---

20. 🤝 Contributing

We welcome contributions from the cybersecurity community!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

21. 📄 License

Distributed under the MIT License. See LICENSE for more information.

---

22. 📖 Appendix A: Detailed Architecture Deep Dive

20.1 API Request Lifecycle

When a request enters the HoneyCloud ecosystem, it undergoes a rigorous lifecycle:

1. Ingestion Layer: The ASGI server (Uvicorn) receives the incoming TCP/HTTP connection.
2. Middleware Processing:
   • CORSMiddleware validates cross-origin requests.
   • RateLimitMiddleware checks the IP against Redis (if configured) or in-memory token buckets.
3. Authentication: The get_current_user dependency intercepts the request, decodes the JWT, verifies the signature against JWT_SECRET_KEY, and checks database validity.
4. Routing: FastAPI's internal router matches the path and method to the correct controller.
5. Business Logic: The controller delegates complex tasks (like report generation or ML inference) to the services/ layer.
6. Persistence: SQLAlchemy ORM translates Python objects to SQL queries and commits to the database.
7. Response: Data is serialized via Pydantic schemas and returned as JSON.

20.2 Machine Learning Feature Engineering

The Threat Routing Engine relies on several engineered features:

• payload_length: Integer length of the raw payload.
• special_char_ratio: Float representing the density of non-alphanumeric characters.
• sql_keyword_count: Integer count of words like SELECT, UNION, DROP.
• xss_keyword_count: Integer count of words like <script>, alert, javascript:.
• entropy: Float measuring the Shannon entropy of the payload string, highly effective for detecting obfuscated shells.

20.3 Deployment Topologies

HoneyCloud supports various topologies depending on enterprise needs:

• Standalone: Frontend, Backend, and DB on a single EC2/VPS. Best for small businesses.
• Distributed Sensors: Backend hosted centrally; lightweight Python forwarding scripts deployed across global endpoints.
• High Availability (HA): Backend scaled via Kubernetes, Redis for Celery task queuing, and PostgreSQL for distributed data consistency.

Built with ❤️ for the Cybersecurity Community.
_{Co-authored by Anand Bora and Ganesh Kambli.}