༺ MEPHALA ༻

Daedric Deception Platform
_{Advanced Honeypot System with ML-Powered Threat Intelligence}

Proprietary Notice: This repository is proprietary and all rights are reserved. Unauthorized use, copying, modification, distribution, or sale is prohibited. Fixed fingerprint: MEPHALA-FP-2025-eac5a8a58376b2fc1fb6ebef9e5b75c459bc5f8968b6d0ad60c9820a5d018659. For permissions or inquiries, contact [email protected].

                         ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
                      ▄█▀                                                     ▀█▄
                    ▄█▀  ███╗   ███╗███████╗██████╗ ██╗  ██╗ █████╗ ██╗      █████╗  ▀█▄
                   █▀    ████╗ ████║██╔════╝██╔══██╗██║  ██║██╔══██╗██║     ██╔══██╗   ▀█
                  █▌     ██╔████╔██║█████╗  ██████╔╝███████║███████║██║     ███████║    ▐█
                  █▌     ██║╚██╔╝██║██╔══╝  ██╔═══╝ ██╔══██║██╔══██║██║     ██╔══██║    ▐█
                   █▄    ██║ ╚═╝ ██║███████╗██║     ██║  ██║██║  ██║███████╗██║  ██║   ▄█
                    ▀█▄  ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝ ▄█▀
                      ▀█▄                                                         ▄█▀
                         ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
                                    ╔═════════════════════════════════╗
                                    ║    DAEDRIC PRINCE OF SECRETS    ║
                                    ║       The Webspinner v1.0       ║
                                    ╚═════════════════════════════════╝

╔═══════════════════════════════════════════════════════════════╗ ║ ║ ║ "Go now, weave your web across the network. ║ ║ Let the secrets flow to you. ║ ║ Let the lies trap the unwary. ║ ║ The Webspinner watches. The Webspinner waits." ║ ║ ║ ║ — Blessing of Mephala ║ ║ ║ ╚═══════════════════════════════════════════════════════════════╝

---

༺ What is Mephala? ༻

Mephala is a high-interaction honeypot that simulates vulnerable network services to trap attackers and harvest intelligence.

┌──────────────┐                                              ┌──────────────┐
│   ATTACKER   │ ──► Thinks it's a real server ──► TRAPPED ──►│  MEPHALA DB  │
└──────────────┘                                              └──────────────┘
                                                                     │
                              Credentials, commands, payloads,       │
                              IPs, techniques, malware samples       │
                                                                     ▼
                                                              ┌──────────────┐
                                                              │  DASHBOARD   │
                                                              │  Real-time   │
                                                              └──────────────┘

Named after the Daedric Prince of secrets, lies, and webs of deceit from The Elder Scrolls V: Skyrim.

---

༺ The Traps ༻

Mephala weaves three deadly threads to ensnare intruders:

Thread	Port	Disguise	What It Captures
🔐 SSH	2222	Linux OpenSSH server	Usernames, passwords, shell commands, session recordings
🌐 HTTP	8080	WordPress, phpMyAdmin	SQL injection, XSS attempts, file uploads, request payloads
📁 FTP	2121	vsftpd file server	Credentials, uploaded malware, directory traversal attempts

SSH Trap Features

◈ Credential harvesting (username/password capture)
◈ Fake shell with 25+ Linux commands (ls, cat, wget, curl, etc.)
◈ Virtual filesystem (/etc/passwd, /etc/shadow, realistic structure)
◈ Session recording (every keystroke logged)
◈ Malicious command detection (wget, curl, chmod +x patterns)

HTTP Trap Features

◈ WordPress login simulation (wp-login.php, wp-admin)
◈ phpMyAdmin honeytokens
◈ SQL injection detection (UNION, SELECT, DROP, etc.)
◈ XSS payload capture (<script>, onerror, javascript:)
◈ RCE attempt detection (;, |, $(), backticks)
◈ File upload quarantine

FTP Trap Features

◈ Anonymous and authenticated access
◈ Passive (PASV) and Active (PORT) mode support
◈ Uploaded file capture and quarantine
◈ Directory listing with fake files
◈ Path traversal detection (../, %2e%2e)

---

༺ The Spider — ML Engine ༻

Every attack is analyzed by Mephala's machine learning brain:

                    ┌─────────────────┐
    Attack ────────►│  PREPROCESSOR   │──── Feature Extraction
                    └────────┬────────┘     (TF-IDF, patterns, IP analysis)
                             │
                             ▼
                    ┌─────────────────┐
                    │   CLASSIFIER    │──── Random Forest
                    │  (Random Forest)│     Multi-class classification
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │ ANOMALY DETECTOR│──── Isolation Forest
                    │(Isolation Forest)│    Zero-day detection
                    └────────┬────────┘
                             │
                             ▼
              ┌──────────────────────────────┐
              │  THREAT CLASSIFICATION       │
              │  + Severity Score (1-10)     │
              │  + Confidence Level          │
              └──────────────────────────────┘

Threat Classifications

Type	Description	Severity
reconnaissance	Port scanning, service enumeration	🟢 Low
brute_force	Credential stuffing, password spraying	🟡 Medium
sql_injection	Database manipulation attempts	🔴 High
xss	Cross-site scripting payloads	🟡 Medium
rce	Remote code execution attempts	⚫ Critical
path_traversal	Directory escape attempts	🟠 High
credential_theft	Password/token harvesting	🟠 High

---

༺ The Eye — Dashboard ༻

Real-time visualization of the web's activity:

View	Description
Live Feed	Real-time stream of attacks as they happen
World Map	Geographic visualization of attack origins (Leaflet)
Timeline	Attack frequency over time (Chart.js)
Statistics	Total attacks, unique IPs, severity breakdown
Attack Details	Deep dive into individual attack sessions

---

༺ Use Cases ༻

Purpose	Benefit
Threat Research	Study real attacker behavior, TTPs, and tools
Threat Intelligence	Collect IOCs (IPs, payloads, signatures, malware)
Early Warning System	Detect attackers probing your network before they hit real assets
Deception Defense	Waste attacker time and resources on fake targets
Security Training	Learn attack patterns in a safe, controlled environment
SOC Enrichment	Feed captured data into SIEM/SOAR platforms

---

༺ Architecture ༻

mephala/
├── core/                   # ◈ System Core
│   ├── base_service.py     #   Abstract honeypot base class
│   ├── config.py           #   Pydantic configuration management
│   ├── database.py         #   SQLAlchemy async ORM (PostgreSQL/SQLite)
│   ├── honeypot.py         #   Main orchestrator & lifecycle manager
│   └── logger.py           #   Structured logging (JSON/text)
│
├── services/               # ◈ Honeypot Services
│   ├── ssh_honeypot.py     #   SSH trap (asyncssh)
│   ├── http_honeypot.py    #   HTTP trap (aiohttp)
│   ├── ftp_honeypot.py     #   FTP trap (asyncio)
│   └── utils/
│       ├── fake_filesystem.py   # Virtual Linux filesystem
│       ├── response_templates.py # Realistic banners & responses
│       └── session_manager.py    # Session tracking & statistics
│
├── ml/                     # ◈ Machine Learning Pipeline
│   ├── preprocessor.py     #   Feature extraction (TF-IDF, patterns)
│   ├── models.py           #   Random Forest + Isolation Forest
│   ├── trainer.py          #   Training pipeline with GridSearchCV
│   └── predictor.py        #   Real-time classification with caching
│
├── api/                    # ◈ REST API (FastAPI)
│   ├── server.py           #   Application factory, CORS, lifespan
│   ├── auth.py             #   JWT authentication (passlib/bcrypt)
│   ├── models.py           #   Pydantic request/response schemas
│   └── routes/
│       ├── attacks.py      #   CRUD endpoints for attacks
│       ├── stats.py        #   Statistics & analytics endpoints
│       └── websocket.py    #   Real-time WebSocket feed
│
├── dashboard/              # ◈ Frontend (Vue.js 3)
│   └── src/
│       ├── components/     #   StatCard, LiveFeed, Charts
│       ├── views/          #   Dashboard, Attacks, AttackMap
│       ├── stores/         #   Pinia state management
│       └── services/       #   Axios API client
│
├── docker/                 # ◈ Containerization
│   ├── Dockerfile          #   Multi-stage build, non-root user
│   ├── docker-compose.yml  #   Full stack orchestration
│   └── nginx.conf          #   Reverse proxy configuration
│
└── scripts/                # ◈ Utilities
    ├── setup.sh            #   Automated environment setup
    ├── train_models.py     #   ML model training CLI
    └── seed_database.py    #   Test data generation

---

༺ Quick Start ༻

Docker (Recommended)

# Clone the artifact
git clone https://github.com/ind4skylivey/mephala.git
cd mephala

# Configure secrets
cp .env.example .env
nano .env

# Summon the web
cd docker && docker-compose up -d

# Watch the threads
docker-compose logs -f mephala

Manual Installation

# Clone
git clone https://github.com/ind4skylivey/mephala.git
cd mephala

# Setup environment
chmod +x scripts/setup.sh
./scripts/setup.sh

# Initialize database
alembic upgrade head

# Start services (3 terminals)
python core/honeypot.py                        # Honeypot traps
uvicorn api.server:app --reload --port 8000    # REST API
cd dashboard && npm install && npm run dev     # Dashboard

---

༺ API Reference ༻

Authentication

# Obtain JWT token
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

Endpoints

Method	Endpoint	Description
POST	/api/v1/auth/login	Get JWT access token
GET	/api/v1/attacks	List attacks (paginated, filterable)
GET	/api/v1/attacks/{id}	Get attack details with related data
POST	/api/v1/attacks/search	Advanced search with filters
DELETE	/api/v1/attacks/{id}	Delete attack record
GET	/api/v1/stats/overview	Dashboard statistics
GET	/api/v1/stats/timeline	Attack frequency over time
GET	/api/v1/stats/geographic	Geographic distribution
GET	/api/v1/stats/top-attackers	Most active source IPs
GET	/api/v1/stats/attack-types	Attack type distribution
WS	/ws/live	Real-time attack feed

---

༺ Configuration ༻

Environment Variables

# Core
MEPHALA_ENV=production
DEBUG=false

# Database (PostgreSQL recommended)
DATABASE_URL=postgresql+asyncpg://mephala:secret@localhost:5432/mephala

# Cache
REDIS_URL=redis://localhost:6379/0

# API Security
API_SECRET_KEY=your-32-char-secret-key
API_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Service Ports
SSH_PORT=2222
HTTP_PORT=8080
FTP_PORT=2121

# Logging
LOG_LEVEL=INFO
LOG_FORMAT=json

---

༺ Tech Stack ༻

Layer	Technology
Language	Python 3.10+
Async Framework	asyncio, asyncssh, aiohttp
API	FastAPI, Uvicorn
Database	PostgreSQL (async), SQLAlchemy 2.0
Cache	Redis
ML	scikit-learn (Random Forest, Isolation Forest)
Frontend	Vue.js 3, Pinia, Chart.js, Leaflet
Containerization	Docker, docker-compose
Reverse Proxy	nginx

---

༺ Testing ༻

# Run all tests
pytest tests/ -v

# With coverage report
pytest tests/ --cov=core --cov=services --cov=ml --cov=api

# Results
============================= 155 passed ==============================

---

༺ Why Mephala? ༻

How does Mephala compare to other honeypot frameworks?

Feature	Mephala	Cowrie	T-Pot	Dionaea	HoneyTrap
SSH Honeypot	✅	✅	✅	❌	✅
HTTP Honeypot	✅	❌	✅	✅	✅
FTP Honeypot	✅	❌	✅	✅	✅
ML Classification	✅	❌	❌	❌	❌
Anomaly Detection	✅	❌	❌	❌	❌
Auto Threat Scoring	✅	❌	❌	❌	❌
Real-time Dashboard	✅ Vue.js	❌	✅ Kibana	❌	❌
WebSocket Live Feed	✅	❌	❌	❌	❌
REST API	✅ FastAPI	❌	❌	❌	❌
Single Codebase	✅ Python	✅ Python	❌ Multi	❌ C	✅ Go
Modern Async	✅ asyncio	❌ Twisted	❌	❌	✅
Lightweight	✅	✅	❌ Heavy	✅	✅
Easy Deploy	✅	✅	⚠️ Complex	⚠️	✅

What Makes Mephala Unique

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  🧠 ML-POWERED INTELLIGENCE                                         │
│     → Random Forest classifier for attack categorization            │
│     → Isolation Forest for zero-day anomaly detection               │
│     → Automatic severity scoring (1-10)                             │
│     → Real-time threat classification                               │
│                                                                     │
│  ⚡ MODERN ARCHITECTURE                                              │
│     → Pure Python 3.10+ with native asyncio                         │
│     → FastAPI REST endpoints                                        │
│     → WebSocket real-time streaming                                 │
│     → Vue.js 3 reactive dashboard                                   │
│                                                                     │
│  🎯 ALL-IN-ONE SOLUTION                                             │
│     → SSH + HTTP + FTP in single deployment                         │
│     → No Elasticsearch/Kibana dependency                            │
│     → Lightweight compared to T-Pot (~8GB RAM vs ~256MB)            │
│     → Single language, single codebase                              │
│                                                                     │
│  🕷️ UNIQUE IDENTITY                                                  │
│     → Skyrim-inspired Daedric aesthetic                             │
│     → Professional documentation                                    │
│     → Active development                                            │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

---

༺ Roadmap ༻

• Telnet honeypot
• SMTP honeypot
• MySQL/PostgreSQL honeypot
• Elasticsearch integration
• Slack/Telegram alerting
• MITRE ATT&CK mapping
• Threat feed export (STIX/TAXII)
• Kubernetes Helm chart

---

༺ Warning ༻

⚠️  AUTHORIZED USE ONLY

This tool is intended for:
  → Security research on owned infrastructure
  → Authorized penetration testing engagements
  → Educational and training purposes
  → Threat intelligence gathering on controlled networks

Deploy only on networks you own or have explicit written permission to test.
The authors assume no liability for misuse or damage caused by this software.
Unauthorized deployment may violate local laws and regulations.

---

༺ License ༻

Business Source License 1.1 (BSL)

Copyright (c) 2024 ind4skylivey

┌─────────────────────────────────────────────────────────────────┐
│  ✅ ALLOWED                                                     │
│     → Personal use                                              │
│     → Educational use                                           │
│     → Security research                                         │
│     → Internal company use                                      │
│     → Modification and derivatives                              │
│                                                                 │
│  ❌ NOT ALLOWED (without commercial license)                    │
│     → Offering Mephala as a commercial service                  │
│     → Selling access to honeypot deployments                    │
│     → Reselling threat intelligence data                        │
│                                                                 │
│  📅 CHANGE DATE: January 1, 2028                                │
│     → Automatically converts to GPL-3.0                         │
│     → Full open source after this date                          │
└─────────────────────────────────────────────────────────────────┘

For commercial licensing inquiries: Contact ind4skylivey

---

_{༺ MEPHALA ༻
The Webspinner sees all. The web catches all.}

_{🕷️ Inspired by The Elder Scrolls V: Skyrim 🕷️}