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

Firewall Configuration (Production)

# Allow honeypot ports (adjust based on your setup)
sudo ufw allow 30080/tcp  # Apache honeypot
sudo ufw allow 30800/tcp  # WordPress honeypot
sudo ufw allow 30300/tcp  # Next.js honeypot (CVE-2025-55182/CVE-2025-66478)

# Block direct access to internal services
sudo ufw deny 6379/tcp    # Redis
sudo ufw deny 8081/tcp    # Scanner detector
sudo ufw deny 8082/tcp    # LLM planner
sudo ufw deny 8083/tcp    # Artifact sink

sudo ufw enable

Redis (Built-in)

HoneyKube deploys its own Redis instance as a Kubernetes StatefulSet. You don't need to install or configure Redis separately.

Redis Features:

• Deployed as redis:7-alpine image
• Persistent storage via PersistentVolumeClaim (5Gi)
• AOF persistence enabled (appendonly yes)
• Memory limit: 256MB with LRU eviction
• Health checks configured

Redis Data:

• Session data: session:<src-ip>:<port>
• Artifact metadata: artifact:<sha256>
• Artifact index: artifacts:ip:<src-ip>, artifacts:all

Included Fingerprint Profiles

Apache HTTP Server (Port 8080)

• Simulates Apache 2.4.49 on Ubuntu
• Targets: Path traversal (CVE-2021-41773), RCE, LFI attacks
• NodePort: 30080

WordPress (Port 8000)

• Simulates WordPress 5.9.3 on PHP 7.4
• Targets: XML-RPC attacks, plugin exploits, authentication bypass
• NodePort: 30800

Next.js Vulnerable (Port 3000)

• CVE-2025-55182: React Server Components RCE
• CVE-2025-66478: Prototype Pollution leading to RCE
• Simulates Next.js 14.1.0 with React 19.0.0 RC
• Detects React2Shell scanner by Assetnote
• Targets: Server Actions, Next-Action header manipulation, prototype pollution attacks
• NodePort: 30300

The Next.js profile specifically detects and responds to the React2Shell exploit pattern:

• NEXT_REDIRECT / NEXT_NOT_FOUND indicators
• constructor:constructor prototype pollution chains
• process.mainModule.require('child_process') payloads
• Assetnote scanner User-Agent detection
• `x-act