🍯 HPone - Docker Honeypot Manager

A powerful Docker honeypot management tool with auto-import capabilities

---

🎯 Overview

HPone is a comprehensive Docker-based honeypot management platform that simplifies the deployment, monitoring, and maintenance of security honeypots. With intelligent auto-import features and streamlined command interfaces, HPone makes honeypot management accessible for both production and development environments.

✨ Key Features

• 🚀 Auto-Import System - Seamless honeypot template deployment
• 🐳 Docker Integration - Containerized honeypot environments
• 📊 Real-time Monitoring - Live log streaming and status tracking
• 🔧 Flexible Configuration - YAML-based honeypot definitions
• 🛡️ Multi-Honeypot Support - Manage multiple honeypot types simultaneously
• 💻 Interactive CLI - User-friendly command-line interface with bash completion
• ✏️ Built-in Editor - Edit configurations directly from command line

🎬 Quick Demo

10_hpone_preview_v2_3_1.mp4

---

📁 Project Structure

📦 HPone/
┣ 🚀 app.py                     # Main launcher script
┣ 📂 hpone/                     # Core application directory
┃ ┣ 🎯 app.py                   # Application entry point
┃ ┣ ⚙️ config.py               # Configuration management
┃ ┣ 📂 completion/              # Bash completion scripts
┃ ┣ 📂 core/                    # Core functionality modules
┃ ┗ 📂 scripts/                 # Command implementations
┣ 📂 honeypots/                 # 🍯 YAML honeypot definitions
┣ 📂 template/docker/           # 📋 Base Docker templates
┣ 📂 conf/                      # 🔧 Persistent configurations
┣ 📂 docker/                    # 🐳 Generated build outputs (temp)
┗ 📂 data/                      # 💾 Runtime data & logs
┗ 📋 requirements.txt           # Python dependencies

⚙️ Configuration

Configure HPone behavior by editing the configuration file:

• 📦 Debian Package Installation: /opt/hpone/hpone/config.py
• 🔧 Source Installation: hpone/config.py (in your project directory)

📋 View Configuration Options

# 🎭 Behavior Mode
ALWAYS_IMPORT = True              # Auto-import vs Manual control

# 📍 Path Configuration
HONEYPOT_MANIFEST_DIR = PROJECT_ROOT / "honeypots"    # YAML definitions
TEMPLATE_DOCKER_DIR = PROJECT_ROOT / "template" / "docker"  # Base templates
OUTPUT_DOCKER_DIR = PROJECT_ROOT / "docker"           # Build outputs
DATA_DIR = PROJECT_ROOT / "data"                      # Runtime data

# 🖥️  Display Configuration
LIST_BASIC_MAX_WIDTH = 80         # Basic list width
LIST_DETAILED_MAX_WIDTH = 30      # Detailed list width
STATUS_TABLE_MAX_WIDTH = 40       # Status table width

# 📝 Logging Configuration
USE_EPHEMERAL_LOGGING = True      # Real-time vs Simple output

🚀 Quick Setup

📦 Debian Package Installation (Recommended)

# Download and install the latest .deb package
wget https://github.com/ariafatah0711/HPone/releases/latest/download/hpone_all.deb

sudo apt install -f ./hpone_all.deb
sudo usermod -aG docker $USER

# 🔄 IMPORTANT: Restart your shell session to activate changes
sudo newgrp docker # Restart current shell with: logout and login again, OR open a new terminal window

📍 Installation Location: When installed via Debian package, HPone is located at /opt/hpone/

📂 Debian Package Directory Structure

📦 /opt/hpone/                   # Main installation directory
┣ 🚀 app.py                     # Main application entry point
┣ 📂 hpone/                     # Core application directory
┃ ┣ 🎯 app.py                   # Application launcher
┃ ┣ ⚙️ config.py               # Configuration management
┃ ┣ 📂 completion/              # Bash completion scripts
┃ ┣ 📂 core/                    # Core functionality modules
┃ ┗ 📂 scripts/                 # Command implementations
┣ 📂 honeypots/                 # 🍯 YAML honeypot definitions
┣ 📂 template/docker/           # 📋 Base Docker templates
┣ 📂 conf/                      # 🔧 Persistent configurations
┣ 📂 docker/                    # 🐳 Generated build outputs (temp)
┣ 📂 data/                      # 💾 Runtime data & logs
┗ 📋 requirements.txt           # Python dependencies

🔗 Global Access: The hpone command is available system-wide via /usr/bin/hpone

🔧 Source Installation

# Clone and setup HPone
git clone https://github.com/ariafatah0711/HPone hpone
cd hpone

# 🔧 Setup with global installation & bash completion
chmod +x setup.sh
./setup.sh install

# 🔄 IMPORTANT: Restart your shell session to activate changes
sudo newgrp docker # Restart current shell with: logout and login again, OR open a new terminal window

---

🛠 Manual Installation

📦 Dependencies & Libraries

🔍 Install Required Dependencies

# 🐍 Install Python dependencies
pip3 install -r requirements.txt

# 🐳 Install Docker Engine
sudo apt install docker.io
sudo usermod -aG docker $USER

# 📦 Install Docker Compose
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins
curl -SL https://github.com/docker/compose/releases/download/v2.29.0/docker-compose-linux-x86_64 \
  -o $DOCKER_CONFIG/cli-plugins/docker-compose

# 🔒 Set executable permissions
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose
# Alternative system-wide installation
# sudo chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

# ✅ Verify installation
docker compose version

🌐 Global Installation

🔗 Make HPone Available System-Wide

# 🔒 Set executable permissions
chmod +x app.py

# 🔗 Create symbolic link for global access
sudo ln -s $(pwd)/app.py /usr/local/bin/hpone

# ✅ Test global installation
hpone -h

⌨️ Bash Completion Setup

# Quick setup
chmod +x hpone/completion/install.sh
./hpone/completion/install.sh
exec $SHELL  # Restart shell

🎨 Tab completion works for all commands and honeypot names!

---

🗑️ Uninstall

📦 Debian Package Removal

sudo apt remove hpone # Remove the installed package
sudo apt purge hpone # Optional: Remove configuration files

# 🔄 **IMPORTANT:** Restart your shell session after removal:
exec $SHELL # Restart current shell with: logout and login again, OR open a new terminal window

🔄 Source Installation Removal

# 🧹 Uninstall global installation & bash completion
chmod +x setup.sh
./setup.sh uninstall

# 🔄 IMPORTANT: Restart your shell session after uninstallation
exec $SHELL                       # Restart current shell

# 🗂️ Optional: Remove project directory
cd ..
rm -rf hpone

🎯 Getting Started

🚀 Quick Start

⚙️ Setup

hpone enable cowrie medpot conpot # Enable multiple honeypots
hpone up --all                    # Start all enabled honeypots

📈 Monitor

hpone list -a                 # Check status
hpone logs cowrie             # View logs

💻 Manage

hpone edit cowrie             # Edit configuration
hpone shell cowrie            # Container access
hpone clean --all --data      # Stop & cleanup

🔧 Command Reference

📊 Core Commands

Command	Description	Options	Example
🔍 check	Verify dependencies	-	hpone check
📋 list	Show honeypots	-a	hpone list -a
📈 status	Runtime status	-	hpone status
🔎 inspect	Honeypot details	-	hpone inspect cowrie
✏️ edit	Edit configurations	<honeypot>, --config, --completion	hpone edit cowrie

✨ Edit Features: Smart editor detection • SSH-aware • YAML validation • Interactive recovery • Tab completion

🏃 Lifecycle Commands

Command	Description	Options	Example
⚙️ enable/disable	Toggle honeypot(s)	-	hpone enable cowrie medpot
🚀 up	Start honeypot	--all, --force	hpone up --all
📏 down	Stop honeypot	--all	hpone down cowrie
💻 shell	Container access	-	hpone shell cowrie
📄 logs	Interactive logs	-	hpone logs cowrie
🗑️ clean	Stop & remove	--all, --data, --image, --volume	hpone clean --all --data

🎨 Quick Examples

# 🚀 Basic workflow
hpone enable cowrie conpot
hpone up --all
hpone logs cowrie     # Interactive log viewer
hpone shell cowrie    # Container access
hpone down cowrie

# 📝 Configuration
hpone edit cowrie     # Edit honeypot config
hpone edit --config   # Edit main settings

# 📊 Monitoring
hpone list -a         # Detailed status
hpone status          # Port mappings

# 🗑️ Cleanup
hpone clean --all --data --image --volume

🔍 Troubleshooting

🥾 Dependency Check

hpone check  # Comprehensive system validation

📂 Accessing HPone Files

📦 Debian Package Installation:

# Configuration files
sudo nano /opt/hpone/hpone/config.py

# View honeypot templates
ls /opt/hpone/honeypots/

# Check data directory
ls /opt/hpone/data/

# Access application files
cd /opt/hpone/

🔧 Source Installation:

# Configuration files
nano hpone/config.py

# All files are in your project directory
ls honeypots/
ls data/

📝 Ephemeral Logging System

HPone features real-time ephemeral logging for clean output:

[22:48:02] [INFO] Starting cowrie containers...
[22:48:05] [INFO] Docker network created
[22:48:06] [INFO] Building cowrie image
[22:48:10] [INFO] Container cowrie started
🚀 [UP] cowrie OK (2.3s)

🐛 Issues? Set USE_EPHEMERAL_LOGGING = False in config.py for detailed output.

---

📋 Creating Custom Honeypots

🎨 YAML Configuration Template

Create a new file in honeypots/ directory:

# 🍯 Custom Honeypot Definition
name: myhoneypot
description: "Custom honeypot for HTTP services"
enabled: true

# 📁 Optional: Custom template directory
template_dir: custom/template/path  # Relative or absolute path

# 🌐 Port Configuration
ports:
- host: 8080
  container: 80
  description: "HTTP service"
- host: 8443
  container: 443
  description: "HTTPS service"

# 🌍 Environment Variables (merged with template defaults)
env:
  MY_CUSTOM_VAR: "production_value"
  DEBUG_MODE: "false"
  LOG_LEVEL: "INFO"

# 💾 Volume Mounts
volumes:
- data/myhoneypot/logs:/app/logs           # Persistent logs
- conf/myhoneypot/config.yml:/app/config.yml  # Custom config override

🔑 Key Configuration Fields

Field	Type	Description
template_dir	Optional	Custom template path (relative to project or absolute)
env	Object	Environment variables (merged with template defaults)
ports	Array	Port mappings with optional descriptions
volumes	Array	Volume mounts for data persistence and configuration

---

📝 Important Notes

🚀 Operation Modes

HPone has two modes configured in hpone/config.py:

• 🤖 Auto Mode (ALWAYS_IMPORT=true) - Production ready, auto-manages templates
• 🔧 Manual Mode (ALWAYS_IMPORT=false) - Development friendly, full control

📝 Quick Tips

• ⚠️ Disabled honeypots won't auto-start
• 👍 Use --force to override enabled status
• 💻 shell command requires running containers

---

🤝 Contributing

🎆 Help make HPone better!

1. 🍴 Fork the project
2. 🌱 Create feature branch (git checkout -b feature/amazing-feature)
3. 📝 Commit changes (git commit -m 'Add amazing feature')
4. 🚀 Push to branch (git push origin feature/amazing-feature)
5. 📩 Open Pull Request

---

📄 License

HPone is licensed under the GNU General Public License v3.0 (GPL-3.0) See the LICENSE file for details.

---

🍯 Made with ❤️ for cybersecurity enthusiasts