HoneyKube - Kubernetes-Ready Adaptive Honeypot System

A distributed, AI-powered honeypot system designed for Kubernetes that uses OpenRouter to access multiple LLM providers for generating realistic vulnerable server responses. HoneyKube captures attacker behavior, detects scanning tools, and logs all interactions for security analysis.

Security Warning

NEVER run HoneyKube as root! Honeypots are intentionally exposed to attackers. Running as root could allow attackers to gain elevated privileges if any vulnerability is discovered.

Features

• AI-Powered Responses: Uses OpenRouter to access 100+ LLM models (GPT-4, Claude, Gemini, Llama, etc.) for contextually appropriate vulnerable server responses
• Never Returns 404: Dynamic content generation ensures every path returns realistic vulnerable content - never reveals it's a honeypot
• Scanner Detection: Identifies 25+ scanning tools and exploit frameworks (sqlmap, nmap, Metasploit, React2Shell, WPScan, etc.)
• Session Memory: Tracks attacker sessions with Redis for progressive response generation
• Artifact Capture: Stores uploaded payloads and logs with SHA-256 hashing
• Flexible Fingerprints: YAML-based service profiles with default responses for common sensitive paths
• Exploit Stage Detection: Distinguishes reconnaissance from exploitation attempts
• Kubernetes Native: Designed for horizontal scaling with HPA support
• Modular Configuration: All settings via environment variables

Architecture

Project Structure

HoneyKube/
├── services/
│   ├── port-listener/        # Main honeypot service
│   │   ├── main.py
│   │   ├── requirements.txt
│   │   └── Dockerfile
│   ├── scanner-detector/     # Scanner classification service
│   │   ├── main.py
│   │   ├── requirements.txt
│   │   └── Dockerfile
│   ├── llm-planner/          # AI response generation (OpenRouter)
│   │   ├── main.py
│   │   ├── requirements.txt
│   │   └── Dockerfile
│   └── artifact-sink/        # Logging & artifact storage
│       ├── main.py
│       ├── requirements.txt
│       └── Dockerfile
├── shared/                   # Shared Python modules
│   ├── schemas.py           # Pydantic models
│   ├── redis_client.py      # Redis session management
│   └── utils.py             # Common utilities
├── config/
│   └── fingerprints/        # Service fingerprint profiles
│       ├── apache.yaml
│       ├── wordpress.yaml
│       └── nextjs.yaml      # CVE-2025-55182 & CVE-2025-66478
├── tools/                   # Exploit scanners for testing
│   ├── README.md            # Scanner documentation
│   ├── react2shell_scanner.py  # Next.js RCE scanner
│   ├── wordpress_scanner.py    # WordPress exploit scanner
│   └── apache_scanner.py       # Apache exploit scanner
├── k8s/                     # Kubernetes manifests
│   ├── namespace.yaml
│   ├── configmaps.yaml
│   ├── secrets.yaml
│   ├── redis.yaml
│   ├── scanner-detector.yaml
│   ├── llm-planner.yaml
│   ├── artifact-sink.yaml
│   ├── port-listeners.yaml
│   ├── hpa-network.yaml
│   └── deploy.sh
├── .env.example             # Environment variable template
├── docker-compose.yaml      # Local development
├── Dockerfile.shared        # Shared module build
└── README.md

Exploit Scanners for Testing

The tools/ directory contains real-world exploit scanners to test your honeypots:

# Install dependencies
pip install requests tqdm

# Test Next.js honeypot with React2Shell scanner
python tools/react2shell_scanner.py -u http://localhost:3000 -v

# Test WordPress honeypot
python tools/wordpress_scanner.py -u http://localhost:8000 -v

# Test Apache honeypot
python tools/apache_scanner.py -u http://localhost:80 -v

See tools/README.md for full documentation on available exploits.

Complete Setup Guide (Fresh Machine)

IMPORTANT: Create a Dedicated User (DO NOT RUN AS ROOT!)

Running HoneyKube as root is a serious security risk. Always create a dedicated non-root user:

# Create honeypot user (run these as root, then switch)
sudo useradd -m -s /bin/bash honeykube
sudo passwd honeykube

# Add to docker group (required for Docker)
sudo usermod -aG docker honeykube

# Add sudo access if needed (optional, for kubectl setup)
sudo usermod -aG sudo honeykube

# Switch to the new user
su - honeykube

# Verify you're not root
whoami  # Should output: honeykube
id      # Should show uid != 0

Step 1: Install Dependencies (Ubuntu/Debian)

# Update system
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y curl wget git apt-transport-https ca-certificates gnupg lsb-release

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

# Log out and back in for docker group to take effect
exit
su - honeykube

# Verify Docker installation
docker --version
docker run hello-world

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Step 2: Install Kubernetes Tools

# Install kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
kubectl version --client

# Install minikube (Recommended for development/testing)
curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
minikube start --driver=docker

Step 3: Get an OpenRouter API Key

1. Go to OpenRouter
2. Sign in or create an account
3. Click "Create Key"
4. Copy the key (you'll need it in Step 5)

Note: OpenRouter gives you access to 100+ LLM models including GPT-4, Claude, Gemini, Llama, and more with a single API key!

Step 4: Clone and Configure HoneyKube

# Clone the repository
git clone https://github.com/MohamedAYassin/HoneyKube
cd HoneyKube

# Set proper permissions
chmod -R 750 .
chmod +x k8s/deploy.sh

Step 5: Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit with your API key
nano .env

Update the file with your OpenRouter API key:

OPENROUTER_API_KEY=your-actual-api-key-here

# Optional: Choose a different model (default: google/gemini-2.0-flash-001)
# See https://openrouter.ai/models for all available models
LLM_MODEL=google/gemini-2.0-flash-001

For Kubernetes deployment, also update:

nano k8s/secrets.yaml

stringData:
  OPENROUTER_API_KEY: "your-actual-api-key-here"

Step 6A: Local Development with Docker Compose

# Build and run all services
docker-compose up --build -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f

# Access honeypots:
# Apache: http://localhost:8080
# WordPress: http://localhost:8000
# Next.js: http://localhost:3000 (CVE-2025-55182/CVE-2025-66478)

# Stop services
docker-compose down

Step 6B: Production Kubernetes Deployment

# Build Docker images
docker build -f Dockerfile.shared -t honeykube/shared:latest .
docker build -f services/port-listener/Dockerfile -t honeykube/port-listener:latest .
docker build -f services/scanner-detector/Dockerfile -t honeykube/scanner-detector:latest .
docker build -f services/llm-planner/Dockerfile -t honeykube/llm-planner:latest .
docker build -f services/artifact-sink/Dockerfile -t honeykube/artifact-sink:latest .

# For Minikube/local cluster, images are already available if using minikube docker-env
# For remote clusters, push to your registry:
# docker tag honeykube/port-listener:latest your-registry/honeykube/port-listener:latest
# docker push your-registry/honeykube/port-listener:latest

# Deploy to Kubernetes
cd k8s
./deploy.sh apply

# Verify deployment
kubectl get pods -n honeykube
kubectl get svc -n honeykube

# Access honeypots:
# Apache: http://<node-ip>:30080
# WordPress: http://<node-ip>:30800
# Next.js: http://<node-ip>:30300 (CVE-2025-55182/CVE-2025-66478)

Step 7: Verify Installation

# Test Apache honeypot
curl http://localhost:30080/

# Test WordPress honeypot
curl http://localhost:30800/wp-login.php

# Test Next.js honeypot (React Server Components RCE)
curl http://localhost:30300/

# Check logs
kubectl logs -l app.kubernetes.io/component=port-listener -n honeykube

# View Redis session data
kubectl exec -it redis-0 -n honeykube -- redis-cli KEYS '*'

Step 8: Run Test Suite

HoneyKube includes a comprehensive test script to verify all components:

# Make test script executable
chmod +x k8s/test.sh

# Run tests for Kubernetes deployment
./k8s/test.sh --k8s

# Or for Docker Compose (local) deployment
./k8s/test.sh --local

The test suite checks:

• Pre-flight (user permissions, required tools)
• Kubernetes resources (pods, services, secrets, PVCs)
• Redis connectivity and health
• All service health endpoints
• Honeypot HTTP responses (Apache, WordPress, Next.js)
• Scanner detection functionality (sqlmap, React2Shell)
• Artifact sink logging
• Full request flow integration

Fi