Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction to HoneyBee

Welcome to the HoneyBee documentation! HoneyBee is a distributed honeypot orchestration framework that allows you to deploy, manage, and monitor multiple honeypot nodes from a central manager.

What is HoneyBee?

HoneyBee is a comprehensive honeypot management platform consisting of three main components:

  1. HoneyBee Core - The central orchestration manager (written in Rust)
  2. HoneyBee Node - Individual honeypot nodes that connect to the manager (Go implementation)
  3. HoneyBee Potstore - Repository of pre-configured honeypots ready for deployment

Key Features

  • 🔐 Secure by Design: TLS 1.3 encryption and TOTP authentication
  • 🌐 Distributed: Manage multiple nodes from a central location
  • 📡 Real-time Communication: JSON-based Protocol v2 over TCP/TLS
  • 🔄 Resilient: Automatic reconnection and error handling
  • 📊 Observable: Comprehensive logging and monitoring
  • 🍯 Honeypot Management: Automatic installation and lifecycle management
  • 🚀 Cross-Platform: Linux, Windows, and macOS support
  • 🧪 Beta Status: Actively developed and tested

System Architecture

┌─────────────────────────────────────────────────────────┐
│              HoneyBee Core Manager                       │
│              (Rust - TCP Server)                         │
│                                                           │
│  - Node Registry & Management                            │
│  - Message Routing (Protocol v2)                         │
│  - Status Tracking                                        │
│  - Backend API (Port 9002)                               │
│  - WebSocket Proxy (Port 9003)                           │
└──────────────┬──────────────────────────────────────────┘
               │
               │ TCP/TLS + Protocol v2
               │ Port 9001
               │
       ┌───────┴────────┬──────────────┬──────────────┐
       │                │              │              │
   ┌───▼───┐        ┌───▼───┐     ┌───▼───┐     ┌───▼───┐
   │ Node  │        │ Node  │     │ Node  │     │ Node  │
   │  (Go) │        │  (Go) │     │  (Go) │     │  (Go) │
   └───┬───┘        └───┬───┘     └───┬───┘     └───┬───┘
       │                │              │              │
       │                │              │              │
   ┌───▼───┐        ┌───▼───┐     ┌───▼───┐     ┌───▼───┐
   │Cowrie │        │HonnyP │     │Cowrie │     │Dionaea│
   │Pot    │        │otter  │     │Pot    │     │Pot    │
   └───────┘        └───────┘     └───────┘     └───────┘

Component Overview

HoneyBee Core

The central manager that orchestrates all nodes and honeypots:

  • Node Registration: Nodes connect and register with TOTP authentication
  • Command Distribution: Send commands to nodes (install, start, stop honeypots)
  • Status Monitoring: Track node and honeypot status in real-time
  • Event Aggregation: Collect events from all honeypots
  • Backend API: RESTful API for external integrations
  • WebSocket Proxy: Real-time updates via WebSocket

Repository: honeybee_core

HoneyBee Node

Go-based nodes that connect to the Core manager:

  • Connection Management: Automatic reconnection with exponential backoff
  • Honeypot Installation: Automatically install honeypots from Potstore
  • Honeypot Lifecycle: Start, stop, restart, and monitor honeypots
  • Event Forwarding: Forward honeypot events to Core in real-time
  • TLS 1.3 Encryption: Secure communication with the manager
  • TOTP Authentication: Time-based one-time password support

Repository: honeybee_node

HoneyBee Potstore

Repository of pre-configured honeypots:

  • Pre-configured Honeypots: Cowrie, HonnyPotter, and more
  • Automatic Integration: Honeypots automatically forward events to nodes
  • Easy Installation: Nodes automatically install from Potstore
  • Standardized Format: Consistent structure and configuration

Repository: honeybee_potstore

How It Works

  1. Deploy HoneyBee Core - Start the central manager
  2. Deploy HoneyBee Nodes - Nodes connect to Core and register
  3. Install Honeypots - Core sends commands to nodes to install honeypots from Potstore
  4. Monitor Attacks - Honeypots capture attacks and forward events to Core
  5. Analyze Data - Core aggregates all events for analysis

For New Users

For Node Operators

For System Administrators

For Developers

Status

Current Version: Beta (v1.0.0)
Protocol Version: v2
Status: Actively developed and tested

Getting Help

License

HoneyBee is open-source software licensed under MIT. See the LICENSE files in each repository for details.

Quick Start Guide

This guide will help you get HoneyBee up and running quickly. We’ll deploy HoneyBee Core and connect a HoneyBee Node.

Prerequisites

  • HoneyBee Core: Rust 1.75+ (nightly)
  • HoneyBee Node: Go 1.21+
  • For Honeypots: Python 3.7+ or PHP 7.4+, Git

Step 1: Deploy HoneyBee Core

# Clone the repository
git clone https://github.com/H0neyBe/honeybee_core.git
cd honeybee_core

# Build and run with Docker Compose
docker-compose up -d

# Check status
docker-compose ps

The Core will be available on:

  • Node Port: 9001 (for node connections)
  • Backend API: 9002 (for API access)
  • WebSocket Proxy: 9003 (for WebSocket connections)

Using Cargo (Development)

# Clone the repository
git clone https://github.com/H0neyBe/honeybee_core.git
cd honeybee_core

# Build
cargo build --release

# Run
cargo run --release

Step 2: Deploy HoneyBee Node

Using Pre-built Binary

# Download from releases (when available)
# Or build from source (see below)

Building from Source

# Clone the repository
git clone https://github.com/H0neyBe/honeybee_node.git
cd honeybee_node

# Build
make build

# Generate configuration
./build/honeybee-node -gen-config

Configure the Node

Edit configs/config.yaml:

node:
  name: "my-first-node"
  type: "Full"

server:
  address: "localhost:9001"  # Core manager address

tls:
  enabled: false  # Set to true in production

auth:
  totp_enabled: false  # Set to true in production

honeypot:
  enabled: true
  base_dir: "~/.honeybee/honeypots"

Run the Node

./build/honeybee-node -config configs/config.yaml

You should see:

Starting HoneyBee Node...
Connected to server successfully
Registration accepted
Node started successfully, running...

Step 3: Verify Connection

Check the Core logs to see the node registration:

Node registered: my-first-node (ID: 12345)
Node status: Running

Step 4: Install a Honeypot

Once the node is connected, you can install honeypots. This is typically done via the Core’s API or CLI.

Example: Install Cowrie

The Core will send an InstallPot command to the node:

{
  "version": 2,
  "message": {
    "NodeCommand": {
      "node_id": 12345,
      "command": {
        "InstallPot": {
          "pot_id": "cowrie-01",
          "honeypot_type": "cowrie",
          "config": {
            "ssh_port": "2222",
            "telnet_port": "2223"
          },
          "auto_start": true
        }
      }
    }
  }
}

The node will:

  1. Clone the Potstore repository
  2. Install Cowrie with dependencies
  3. Configure HoneyBee integration
  4. Start the honeypot automatically

Step 5: Monitor Events

Once a honeypot is running, it will forward events to the Core. You can monitor these events via:

  • Core Logs: Check Core console output
  • Backend API: Query events via REST API (port 9002)
  • WebSocket: Real-time updates via WebSocket (port 9003)

Next Steps

Troubleshooting

Node Won’t Connect

  1. Verify Core is running: curl http://localhost:9002/health
  2. Check Core address in node config
  3. Check firewall rules
  4. Enable debug logging: ./build/honeybee-node -config configs/config.yaml -debug

Honeypot Installation Fails

  1. Ensure Python/PHP is installed
  2. Check disk space
  3. Verify Git is available
  4. Review node logs for errors

See Troubleshooting Guide for more help.

Installation Overview

This guide covers installing all HoneyBee components.

Component Installation

HoneyBee Core

The central orchestration manager.

Options:

  • Docker - Recommended for production
  • Cargo - For development

Requirements:

  • Rust 1.75+ (nightly)
  • Linux, Windows, or macOS

HoneyBee Node

Individual honeypot nodes.

Options:

Requirements:

  • Go 1.21+ (for building)
  • Static binary (no runtime dependencies)
  • Linux, Windows, or macOS

HoneyBee Potstore

Honeypot repository (automatically cloned by nodes).

No installation required - Nodes automatically clone from GitHub.

Installation Order

  1. Install HoneyBee Core first
  2. Install HoneyBee Nodes and connect to Core
  3. Honeypots are installed automatically via Core commands

System Requirements

Minimum Requirements

  • CPU: 1 core
  • RAM: 512 MB
  • Disk: 1 GB free space
  • Network: TCP connectivity between Core and Nodes
  • CPU: 2+ cores
  • RAM: 2 GB
  • Disk: 10 GB free space (for honeypots)
  • Network: Low latency (< 100ms)

For Honeypots

  • Python 3.7+ (for Python-based honeypots like Cowrie)
  • PHP 7.4+ (for PHP-based honeypots like HonnyPotter)
  • Git (for cloning Potstore)

Platform-Specific Notes

Linux

All components work natively on Linux. Systemd service files available.

Windows

  • Core: Requires Rust nightly
  • Node: Pre-built Windows binaries available
  • Honeypots: Python/PHP must be installed

macOS

  • Core: Requires Rust nightly
  • Node: Pre-built macOS binaries available
  • Honeypots: Python/PHP via Homebrew

Verification

After installation, verify each component:

Verify Core

# Check if Core is running
curl http://localhost:9002/health

# Or check logs
docker logs honeybee-core

Verify Node

# Check node status
./build/honeybee-node -version

# Validate configuration
./build/honeybee-node -config configs/config.yaml -validate

Verify Honeypots

Honeypots are verified automatically when installed. Check node logs for installation status.

Next Steps

Architecture Overview

This document provides a high-level overview of the HoneyBee architecture.

System Components

HoneyBee consists of three main components:

  1. HoneyBee Core - Central orchestration manager
  2. HoneyBee Node - Distributed honeypot nodes
  3. HoneyBee Potstore - Honeypot repository

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                    HoneyBee Core                             │
│                    (Rust Application)                        │
│                                                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │            Node Manager                              │    │
│  │  - Node Registration                                 │    │
│  │  - Status Tracking                                    │    │
│  │  - Command Distribution                               │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │            Backend Manager                            │    │
│  │  - REST API (Port 9002)                              │    │
│  │  - WebSocket Proxy (Port 9003)                       │    │
│  │  - Event Aggregation                                  │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                               │
│  ┌─────────────────────────────────────────────────────┐    │
│  │            Message Protocol (v2)                      │    │
│  │  - JSON over TCP/TLS                                  │    │
│  │  - Node Port: 9001                                    │    │
│  └─────────────────────────────────────────────────────┘    │
└───────────────────────┬───────────────────────────────────────┘
                        │
                        │ Protocol v2 (TCP/TLS)
                        │
        ┌───────────────┴───────────────┐
        │                               │
   ┌────▼────┐                    ┌────▼────┐
   │  Node 1 │                    │  Node 2 │
   │  (Go)   │                    │  (Go)   │
   └────┬────┘                    └────┬────┘
        │                               │
   ┌────▼────┐                    ┌────▼────┐
   │ Cowrie  │                    │HonnyPot │
   │ Pot     │                    │ter Pot  │
   └─────────┘                    └─────────┘

Component Details

HoneyBee Core

Purpose: Central orchestration and management

Responsibilities:

  • Accept node connections
  • Register and authenticate nodes
  • Distribute commands to nodes
  • Aggregate events from nodes
  • Provide API for external systems
  • Track node and honeypot status

Ports:

  • 9001 - Node connections (TCP)
  • 9002 - Backend API (HTTP)
  • 9003 - WebSocket proxy (WS)

Components:

  • NodeManager - Manages node lifecycle
  • BackendManager - Handles API and WebSocket
  • Message Protocol - Protocol v2 implementation

HoneyBee Node

Purpose: Deploy and manage honeypots

Responsibilities:

  • Connect to Core manager
  • Authenticate with TOTP
  • Install honeypots from Potstore
  • Manage honeypot lifecycle (start/stop/restart)
  • Forward honeypot events to Core
  • Report status to Core

Components:

  • NodeClient - Connection management
  • HoneypotManager - Honeypot lifecycle
  • Event Listener - Receives events from honeypots (port 9100)
  • Protocol Handler - Protocol v2 implementation

HoneyBee Potstore

Purpose: Repository of pre-configured honeypots

Structure:

  • Each honeypot in its own directory
  • Standardized installation scripts
  • HoneyBee integration plugins
  • Configuration templates

Honeypots:

  • Cowrie - SSH/Telnet honeypot (Python)
  • HonnyPotter - WordPress login honeypot (PHP)
  • More coming soon…

Communication Flow

Node Registration

Node                    Core
 │                       │
 │─── Connect ──────────>│
 │                       │
 │<── Request TOTP ──────│
 │                       │
 │─── TOTP Code ────────>│
 │                       │
 │<── Registration Ack ──│
 │                       │

Honeypot Installation

Core                    Node                    Potstore
 │                       │                       │
 │─── InstallPot ───────>│                       │
 │                       │─── Clone ────────────>│
 │                       │<── Repository ────────│
 │                       │                       │
 │                       │─── Install ──────────>│
 │                       │<── Configure ────────│
 │                       │                       │
 │<── Status Update ──────│                       │
 │                       │                       │

Event Flow

Honeypot              Node                    Core
 │                      │                       │
 │─── Event ───────────>│                       │
 │   (TCP:9100)         │                       │
 │                      │─── PotEvent ─────────>│
 │                      │   (Protocol v2)       │
 │                      │                       │

Protocol v2

HoneyBee uses Protocol v2 for all communication:

  • Transport: TCP with optional TLS 1.3
  • Format: JSON messages wrapped in envelopes
  • Versioning: Protocol version in envelope
  • Bidirectional: Both Core and Node can initiate messages

See Protocol Specification for details.

Security

Authentication

  • TOTP: Time-based one-time passwords for node registration
  • TLS: Optional TLS 1.3 encryption for all communication

Authorization

  • Nodes authenticate during registration
  • Core validates all commands
  • Honeypots communicate only with their node

Scalability

Horizontal Scaling

  • Deploy multiple Core instances (with load balancing)
  • Deploy unlimited nodes
  • Each node can run multiple honeypots

Vertical Scaling

  • Core: Multi-threaded async (Tokio)
  • Node: Lightweight Go binary
  • Honeypots: Isolated processes

Data Flow

  1. Commands: Core → Node → Honeypot
  2. Events: Honeypot → Node → Core
  3. Status: Node → Core
  4. API: External → Core

Next Steps

HoneyBee Core Overview

HoneyBee Core is the central orchestration manager for the HoneyBee platform. Written in Rust, it manages all nodes, distributes commands, and aggregates events from honeypots.

What is HoneyBee Core?

HoneyBee Core is a distributed honeypot management system that allows you to:

  • Orchestrate Nodes: Manage multiple honeypot nodes from a central location
  • Deploy Honeypots: Install and manage honeypots across all nodes
  • Monitor Status: Track node and honeypot health in real-time
  • Aggregate Events: Collect attack data from all honeypots
  • Provide API: RESTful API and WebSocket for external integrations

Key Features

  • 🚀 High Performance: Built with Rust and Tokio async runtime
  • 🔐 Secure: TLS 1.3 support and TOTP authentication
  • 📡 Real-time: WebSocket proxy for live updates
  • 🌐 Distributed: Manage nodes across networks
  • 📊 Observable: Comprehensive logging and monitoring
  • 🔌 Extensible: Backend API for custom integrations

Architecture

Core consists of three main components:

  1. Node Manager - Handles node registration and communication
  2. Backend Manager - Provides REST API and WebSocket proxy
  3. Message Protocol - Protocol v2 implementation

Ports

  • 9001 - Node connections (TCP/TLS)
  • 9002 - Backend API (HTTP)
  • 9003 - WebSocket proxy (WS)

Components

Node Manager

Manages all connected nodes:

  • Node registration with TOTP
  • Status tracking
  • Command distribution
  • Event aggregation

Backend Manager

Provides external interfaces:

  • REST API for programmatic access
  • WebSocket proxy for real-time updates
  • Event streaming

Message Protocol

Implements Protocol v2:

  • JSON message format
  • Versioned envelopes
  • Bidirectional communication

Quick Start

# Using Docker
docker-compose up -d

# Or using Cargo
cargo run --release

Configuration

Core configuration is in bee_config.toml:

[server]
host = "127.0.0.1"
node_port = 9001
backend_port = 9002
debug = false

[logging]
level = "debug"
folder = "logs"
force_color = true

[proxy]
enabled = true
host = "0.0.0.0"
port = 9003

Next Steps

HoneyBee Core Installation

This guide covers installing HoneyBee Core from source or using Docker.

Prerequisites

  • Rust: 1.75+ (nightly toolchain)
  • OS: Linux, Windows, or macOS
  • Network: Ports 9001, 9002, 9003 available

Installation Methods

The easiest way to run HoneyBee Core:

# Clone repository
git clone https://github.com/H0neyBe/honeybee_core.git
cd honeybee_core

# Build and run
docker-compose up -d

# Check status
docker-compose ps
docker logs honeybee-core

Method 2: Cargo (Development)

For development or custom builds:

# Clone repository
git clone https://github.com/H0neyBe/honeybee_core.git
cd honeybee_core

# Install Rust nightly (if not already installed)
rustup toolchain install nightly
rustup default nightly

# Build
cargo build --release

# Run
cargo run --release

Configuration

Core uses bee_config.toml for configuration:

[server]
host = "127.0.0.1"        # Bind address
node_port = 9001          # Port for node connections
backend_port = 9002       # Port for backend API
debug = false             # Enable debug mode

[logging]
level = "debug"           # Log level: trace, debug, info, warn, error
folder = "logs"          # Log directory
force_color = true       # Force colored output

[proxy]
enabled = true           # Enable WebSocket proxy
host = "0.0.0.0"        # Proxy bind address
port = 9003             # Proxy port

Verification

Check if Core is Running

# Check process
ps aux | grep honeybee_core

# Or check Docker
docker ps | grep honeybee-core

# Check logs
docker logs honeybee-core
# Or
tail -f logs/debug.log

Test Node Port

# Test node connection port
telnet localhost 9001

# Or with netcat
nc -zv localhost 9001

Test Backend API

# Health check
curl http://localhost:9002/health

# Or check API endpoint
curl http://localhost:9002/api/v1/nodes

Running with Tracing

For performance analysis:

cargo run --release --features tracing

Then connect with Tracy profiler.

Next Steps

HoneyBee Core Configuration

Complete configuration reference for HoneyBee Core.

Configuration File

Core uses bee_config.toml for configuration. The file is loaded from the current directory or can be specified via command line.

Configuration Sections

[server]

Server configuration:

[server]
host = "127.0.0.1"        # Bind address for node connections
node_port = 9001          # Port for node connections (TCP)
backend_port = 9002       # Port for backend API (HTTP)
debug = false             # Enable debug mode

Options:

  • host - IP address or hostname to bind to (default: “127.0.0.1”)
  • node_port - Port for node connections (default: 9001)
  • backend_port - Port for backend API (default: 9002)
  • debug - Enable debug mode for additional logging (default: false)

[logging]

Logging configuration:

[logging]
level = "debug"           # Log level
folder = "logs"           # Log directory
force_color = true        # Force colored output

Options:

  • level - Log level: trace, debug, info, warn, error (default: “debug”)
  • folder - Directory for log files (default: “logs”)
  • force_color - Force colored output even when not in TTY (default: true)

[proxy]

WebSocket proxy configuration:

[proxy]
enabled = true           # Enable WebSocket proxy
host = "0.0.0.0"        # Bind address
port = 9003             # Proxy port

Options:

  • enabled - Enable WebSocket proxy (default: true)
  • host - Bind address for proxy (default: “0.0.0.0”)
  • port - Port for WebSocket connections (default: 9003)

Example Configurations

Development

[server]
host = "127.0.0.1"
node_port = 9001
backend_port = 9002
debug = true

[logging]
level = "debug"
folder = "logs"
force_color = true

[proxy]
enabled = true
host = "127.0.0.1"
port = 9003

Production

[server]
host = "0.0.0.0"
node_port = 9001
backend_port = 9002
debug = false

[logging]
level = "info"
folder = "/var/log/honeybee"
force_color = false

[proxy]
enabled = true
host = "0.0.0.0"
port = 9003

Environment Variables

Core can also be configured via environment variables (future feature).

Configuration Validation

Core validates configuration on startup. Invalid configuration will cause Core to exit with an error message.

Next Steps

HoneyBee Core Deployment

Production deployment guide for HoneyBee Core.

Deployment Methods

Easiest and most portable:

# Build image
docker build -t honeybee-core:latest .

# Run container
docker run -d \
  --name honeybee-core \
  -p 9001:9001 \
  -p 9002:9002 \
  -p 9003:9003 \
  -v $(pwd)/bee_config.toml:/app/bee_config.toml:ro \
  -v honeybee-logs:/app/logs \
  honeybee-core:latest

Systemd Service

For Linux systems:

# Copy binary
sudo cp target/release/honeybee_core /usr/local/bin/
sudo chmod +x /usr/local/bin/honeybee_core

# Create systemd service
sudo tee /etc/systemd/system/honeybee-core.service > /dev/null <<EOF
[Unit]
Description=HoneyBee Core
After=network.target

[Service]
Type=simple
User=honeybee
ExecStart=/usr/local/bin/honeybee_core
WorkingDirectory=/etc/honeybee
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Create user and directories
sudo useradd -r -s /bin/false honeybee
sudo mkdir -p /etc/honeybee /var/log/honeybee
sudo chown honeybee:honeybee /etc/honeybee /var/log/honeybee

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable honeybee-core
sudo systemctl start honeybee-core

Security Considerations

Firewall

Configure firewall to allow only necessary ports:

# Allow node connections
sudo ufw allow 9001/tcp

# Allow backend API (restrict to internal network)
sudo ufw allow from 10.0.0.0/8 to any port 9002

# Allow WebSocket (restrict as needed)
sudo ufw allow 9003/tcp

TLS (Future)

TLS support for node connections is planned. Currently, nodes can use TLS when connecting.

Non-root User

Always run Core as a non-root user:

sudo useradd -r -s /bin/false honeybee
sudo chown -R honeybee:honeybee /usr/local/bin/honeybee_core /etc/honeybee

Monitoring

Health Checks

# Check API health
curl http://localhost:9002/health

# Check process
systemctl status honeybee-core

Logs

# View logs
tail -f /var/log/honeybee/debug.log

# Or with systemd
journalctl -u honeybee-core -f

Scaling

Horizontal Scaling

Deploy multiple Core instances behind a load balancer:

  • Use sticky sessions for node connections
  • Share state via database (future feature)
  • Load balance API requests

Vertical Scaling

Core is multi-threaded and will use available CPU cores automatically.

Backup

Configuration

Backup bee_config.toml:

cp bee_config.toml bee_config.toml.backup

Logs

Rotate logs regularly:

# Use logrotate
sudo logrotate -f /etc/logrotate.d/honeybee-core

Troubleshooting

Core Won’t Start

  1. Check configuration file syntax
  2. Verify ports are available
  3. Check logs for errors
  4. Ensure user has permissions

Nodes Can’t Connect

  1. Check firewall rules
  2. Verify Core is listening: netstat -tuln | grep 9001
  3. Check Core logs for connection attempts
  4. Verify network connectivity

Next Steps

Docker Deployment

Deploy HoneyBee Core using Docker.

Quick Start

# Clone repository
git clone https://github.com/H0neyBe/honeybee_core.git
cd honeybee_core

# Start with docker-compose
docker-compose up -d

# Check status
docker-compose ps
docker logs honeybee-core

Docker Compose

The docker-compose.yml file:

version: '3.8'

services:
  honeybee-core:
    image: ${DOCKERHUB_USERNAME:-h0neybe}/honeybee-core:latest
    container_name: honeybee-core
    ports:
      - "9001:9001"  # Node port
      - "9002:9002"  # Backend port
      - "9003:9003"  # WebSocket port
    volumes:
      - ./bee_config.toml:/app/bee_config.toml:ro
      - honeybee-logs:/app/logs
    restart: unless-stopped
    environment:
      - RUST_LOG=${RUST_LOG:-info}
    healthcheck:
      test: ["CMD", "nc", "-z", "localhost", "9001"]
      interval: 30s
      timeout: 3s
      start_period: 10s
      retries: 3

volumes:
  honeybee-logs:

Building Image

# Build from source
docker build -t honeybee-core:latest .

# Or use pre-built image
docker pull h0neybe/honeybee-core:latest

Running Container

# Run with default config
docker run -d \
  --name honeybee-core \
  -p 9001:9001 \
  -p 9002:9002 \
  -p 9003:9003 \
  honeybee-core:latest

# Run with custom config
docker run -d \
  --name honeybee-core \
  -p 9001:9001 \
  -p 9002:9002 \
  -p 9003:9003 \
  -v $(pwd)/bee_config.toml:/app/bee_config.toml:ro \
  -v honeybee-logs:/app/logs \
  honeybee-core:latest

Environment Variables

docker run -d \
  --name honeybee-core \
  -e RUST_LOG=debug \
  honeybee-core:latest

Volumes

  • Config: Mount bee_config.toml as read-only
  • Logs: Use named volume for logs persistence

Health Checks

The container includes a health check that verifies port 9001 is listening.

Networking

Bridge Network (Default)

Containers can communicate via bridge network.

Host Network

For better performance:

network_mode: "host"

Resource Limits

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 2G
    reservations:
      cpus: '1'
      memory: 1G

Troubleshooting

View Logs

docker logs honeybee-core
docker logs -f honeybee-core  # Follow logs

Execute Commands

docker exec -it honeybee-core sh

Check Status

docker ps | grep honeybee-core
docker inspect honeybee-core

Next Steps

Systemd Deployment

Deploy HoneyBee Core as a systemd service on Linux.

Prerequisites

  • Linux system with systemd
  • Rust binary built: target/release/honeybee_core
  • Configuration file: bee_config.toml

Installation Steps

1. Create User

sudo useradd -r -s /bin/false honeybee

2. Create Directories

sudo mkdir -p /usr/local/bin
sudo mkdir -p /etc/honeybee
sudo mkdir -p /var/log/honeybee

3. Install Binary

sudo cp target/release/honeybee_core /usr/local/bin/honeybee_core
sudo chmod +x /usr/local/bin/honeybee_core
sudo chown honeybee:honeybee /usr/local/bin/honeybee_core

4. Install Configuration

sudo cp bee_config.toml /etc/honeybee/bee_config.toml
sudo chmod 644 /etc/honeybee/bee_config.toml
sudo chown honeybee:honeybee /etc/honeybee/bee_config.toml

5. Create Service File

sudo tee /etc/systemd/system/honeybee-core.service > /dev/null <<EOF
[Unit]
Description=HoneyBee Core Manager
After=network.target

[Service]
Type=simple
User=honeybee
Group=honeybee
WorkingDirectory=/etc/honeybee
ExecStart=/usr/local/bin/honeybee_core
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

# Security settings
NoNewPrivileges=true
PrivateTmp=true

# Resource limits
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

6. Set Permissions

sudo chown -R honeybee:honeybee /etc/honeybee /var/log/honeybee
sudo chmod 755 /etc/honeybee
sudo chmod 755 /var/log/honeybee

7. Enable and Start

sudo systemctl daemon-reload
sudo systemctl enable honeybee-core
sudo systemctl start honeybee-core

Service Management

Start Service

sudo systemctl start honeybee-core

Stop Service

sudo systemctl stop honeybee-core

Restart Service

sudo systemctl restart honeybee-core

Check Status

sudo systemctl status honeybee-core

View Logs

# Journal logs
sudo journalctl -u honeybee-core -f

# Or view last 100 lines
sudo journalctl -u honeybee-core -n 100

Configuration

Edit configuration:

sudo nano /etc/honeybee/bee_config.toml
sudo systemctl restart honeybee-core

Log Rotation

Create logrotate config:

sudo tee /etc/logrotate.d/honeybee-core > /dev/null <<EOF
/var/log/honeybee/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 honeybee honeybee
    sharedscripts
    postrotate
        systemctl reload honeybee-core > /dev/null 2>&1 || true
    endscript
}
EOF

Troubleshooting

Service Won’t Start

# Check status
sudo systemctl status honeybee-core

# Check logs
sudo journalctl -u honeybee-core -n 50

# Check configuration
sudo /usr/local/bin/honeybee_core --help

Permission Issues

# Fix ownership
sudo chown -R honeybee:honeybee /etc/honeybee /var/log/honeybee

# Fix permissions
sudo chmod 755 /etc/honeybee
sudo chmod 755 /var/log/honeybee

Port Already in Use

# Find process using port
sudo lsof -i :9001

# Kill process (if needed)
sudo kill <PID>

Next Steps

HoneyBee Core Architecture

Technical architecture of HoneyBee Core.

Overview

HoneyBee Core is built with Rust using the Tokio async runtime for high-performance concurrent operations.

Components

Node Manager

Manages all connected nodes:

  • Node Registration: Handles node connections and registration
  • Status Tracking: Tracks node and honeypot status
  • Command Distribution: Sends commands to nodes
  • Event Aggregation: Collects events from nodes

Location: src/node_manager/manager.rs

Backend Manager

Provides external interfaces:

  • REST API: HTTP API on port 9002
  • WebSocket Proxy: WebSocket server on port 9003
  • Event Streaming: Streams events to connected clients

Location: src/backend_manager/manager.rs

Message Protocol

Implements Protocol v2:

  • Message Parsing: Parses JSON Protocol v2 messages
  • Message Routing: Routes messages to appropriate handlers
  • Version Validation: Validates protocol version

Location: bee_message/

Architecture Diagram

┌─────────────────────────────────────────┐
│         HoneyBee Core                    │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │      Node Manager                 │  │
│  │  - Node Registry                  │  │
│  │  - Status Tracking                │  │
│  │  - Command Queue                  │  │
│  └──────────────────────────────────┘  │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │      Backend Manager               │  │
│  │  - REST API (9002)                 │  │
│  │  - WebSocket (9003)                │  │
│  └──────────────────────────────────┘  │
│                                          │
│  ┌──────────────────────────────────┐  │
│  │      Message Protocol             │  │
│  │  - Protocol v2                    │  │
│  │  - JSON Parsing                   │  │
│  └──────────────────────────────────┘  │
└──────────────────────────────────────────┘

Data Flow

Node Registration

Node → Core: NodeRegistration
Core → Node: RegistrationAck
Node → Core: NodeStatusUpdate

Command Distribution

Core → Node: NodeCommand
Node → Core: PotStatusUpdate (progress)
Node → Core: PotStatusUpdate (complete)

Event Aggregation

Honeypot → Node: Event (TCP:9100)
Node → Core: PotEvent (Protocol v2)
Core → Backend: Event (API/WebSocket)

Concurrency

Core uses Tokio for async operations:

  • Non-blocking I/O: All network operations are async
  • Concurrent Connections: Handles multiple nodes simultaneously
  • Message Channels: Uses channels for inter-component communication

State Management

  • Node State: In-memory node registry
  • Honeypot State: Tracked per node
  • Event Buffer: Events buffered before forwarding

Next Steps

HoneyBee Core API

Backend API and CLI reference for HoneyBee Core.

REST API

Base URL: http://localhost:9002

Health Check

GET /health

Check if Core is running.

Response:

{
  "status": "ok"
}

Get Nodes

GET /api/v1/nodes

Get list of all registered nodes.

Response:

{
  "nodes": [
    {
      "node_id": 12345,
      "node_name": "my-node",
      "status": "Running",
      "node_type": "Full"
    }
  ]
}

Get Node

GET /api/v1/nodes/{node_id}

Get details of a specific node.

Response:

{
  "node_id": 12345,
  "node_name": "my-node",
  "status": "Running",
  "node_type": "Full",
  "honeypots": [
    {
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "status": "Running"
    }
  ]
}

Get Honeypots

GET /api/v1/honeypots

Get list of all honeypots.

Response:

{
  "honeypots": [
    {
      "node_id": 12345,
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "status": "Running"
    }
  ]
}

WebSocket Proxy

URL: ws://localhost:9003

Real-time updates via WebSocket. Connects to Core’s backend and forwards Protocol v2 messages.

Message Format: JSON Protocol v2 messages

CLI (Future)

Command-line interface for managing Core (planned).

Authentication

API authentication is planned for future versions.

Rate Limiting

Rate limiting is planned for future versions.

Next Steps

HoneyBee Node Overview

The HoneyBee Node is a production-ready Go implementation that connects to the HoneyBee Core manager with enterprise-grade security features.

What is a HoneyBee Node?

A HoneyBee Node is an individual honeypot instance that:

  • Connects to the central HoneyBee Core manager
  • Reports its status via periodic heartbeats
  • Receives and executes commands from the manager
  • Implements the HoneyBee Protocol v2
  • Operates securely with TLS encryption and TOTP authentication

Key Features

🔐 Security First

  • TLS 1.3 Encryption: Secure communication using the latest TLS standard
  • TOTP Authentication: Time-based one-time password for additional security
  • Certificate Validation: Full certificate chain verification
  • Mutual TLS: Optional client certificate authentication
  • Secure Storage: TOTP secrets stored with 0600 permissions

🏗️ Production Ready

  • Clean Architecture: Following Go best practices and project layout
  • Automatic Reconnection: Resilient connection management with backoff
  • Graceful Shutdown: Proper cleanup on termination signals
  • Structured Logging: JSON and text formats with configurable levels
  • Resource Efficient: Minimal CPU and memory footprint

📡 Protocol v2 Compatible

  • Full implementation of HoneyBee Protocol v2
  • JSON-based message format
  • Bidirectional communication
  • Version validation
  • Extensible message types

🚀 Deployment Flexible

  • Single Binary: No runtime dependencies
  • Cross-Platform: Linux, Windows, macOS support
  • Containerized: Docker and Kubernetes ready
  • Service Integration: Systemd service files included
  • Configuration Management: YAML-based configuration

Node Types

Agent Node (Lightweight)

node:
  type: "Agent"
  • Minimal resource usage
  • Basic monitoring capabilities
  • Quick deployment
  • Ideal for edge locations

Full Node

node:
  type: "Full"
  • Full honeypot capabilities
  • Interactive deception workloads
  • Advanced monitoring
  • Rich attack surface

How It Works

1. Connection Establishment

Node → Manager: TCP/TLS Connection
Node → Manager: NodeRegistration (with TOTP)
Manager → Node: RegistrationAck
Node → Manager: NodeStatusUpdate (Running)

2. Heartbeat Loop

Every 30 seconds:
  Node → Manager: NodeStatusUpdate (Running)

3. Command Processing

Manager → Node: NodeCommand("stop")
Node → Manager: NodeStatusUpdate (Stopped)
Node → Manager: NodeEvent(Stopped)
Node → Manager: NodeDrop

Architecture

honeybee_node/
├── cmd/node/              # Application entry point
├── internal/
│   ├── auth/             # TLS + TOTP authentication
│   ├── client/           # Core client logic
│   ├── config/           # Configuration management
│   ├── logger/           # Structured logging
│   └── protocol/         # Protocol v2 definitions
└── configs/              # Configuration files

Communication Flow

sequenceDiagram
    participant Node
    participant Manager
    
    Node->>Manager: Connect (TLS)
    Node->>Manager: NodeRegistration + TOTP
    Manager->>Node: RegistrationAck
    Node->>Manager: NodeStatusUpdate
    
    loop Heartbeat
        Node->>Manager: NodeStatusUpdate (every 30s)
    end
    
    Manager->>Node: NodeCommand
    Node->>Manager: Response

System Requirements

Minimum Requirements

  • OS: Linux, Windows, macOS
  • Memory: 10 MB
  • CPU: Any modern CPU
  • Network: TCP connectivity to manager
  • Disk: 50 MB for binary and logs
  • OS: Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
  • Memory: 20 MB
  • CPU: 1 core
  • Network: Stable connection, low latency to manager
  • Disk: 500 MB for logs and data

Performance Characteristics

  • Memory Usage: ~10-15 MB typical
  • CPU Usage: <1% idle, ~5% during activity
  • Network: Minimal bandwidth (heartbeats only)
  • Startup Time: <1 second
  • Reconnection: Automatic with 5-second delay

Next Steps

  1. Install and set up your first node
  2. Configure security features
  3. Deploy to production

Comparison with Other Implementations

FeatureGo NodePython ExampleRust Example
Production Ready✅❌ (Example)❌ (Example)
TLS 1.3✅❌❌
TOTP Auth✅❌❌
Auto Reconnect✅✅✅
Structured Logging✅❌❌
Configuration Files✅❌❌
Docker Support✅❌❌
Systemd Integration✅❌❌
DocumentationExtensiveMinimalMinimal

The Go implementation is the recommended production node with full security features and comprehensive documentation.

Installation & Quick Start

Get your HoneyBee node running in 5 minutes!

Prerequisites

Choose one of the following:

Option 1: Pre-built Binary (Easiest)

  • Download from releases page

Option 2: Build from Source

  • Go 1.21 or later
  • Git
  • Make (optional but recommended)

Option 3: Docker

  • Docker 20.10+
  • Docker Compose (optional)

Quick Start (Development)

Step 1: Get the Binary

Build from Source

# Clone the repository
git clone https://github.com/yourusername/honeybee.git
cd honeybee/honeybee_node

# Download dependencies
go mod download

# Build
make build
# or: go build -o build/honeybee-node ./cmd/node

Download Pre-built Binary

# Download latest release
wget https://github.com/yourusername/honeybee/releases/latest/download/honeybee-node-linux-amd64

# Make executable
chmod +x honeybee-node-linux-amd64
mv honeybee-node-linux-amd64 honeybee-node

Step 2: Generate Configuration

# Create configs directory
mkdir -p configs

# Generate default configuration
./build/honeybee-node -gen-config

This creates configs/config.yaml with default settings.

Step 3: Configure for Testing

For local testing, edit configs/config.yaml:

node:
  name: "test-node-01"
  type: "Agent"
  address: "0.0.0.0"
  port: 8080

server:
  address: "127.0.0.1:9001"  # Your manager address
  heartbeat_interval: 30
  reconnect_delay: 5

tls:
  enabled: false  # ⚠️ ONLY for local testing!
  # Never disable in production

auth:
  totp_enabled: false  # ⚠️ ONLY for local testing!
  # Never disable in production

log:
  level: "debug"
  format: "text"

⚠️ Warning: This configuration is for testing only. For production, see Security Setup.

Step 4: Start the Manager

First, ensure the HoneyBee Core manager is running:

# In a separate terminal
cd ../honeybee_core
cargo run

The manager should output:

Node Manager listening on: 127.0.0.1:9001

Step 5: Run the Node

./build/honeybee-node -config configs/config.yaml

You should see:

 _   _                       ____             
| | | | ___  _ __   ___ _   | __ )  ___  ___ 
| |_| |/ _ \| '_ \ / _ \ | | |  _ \ / _ \/ _ \
|  _  | (_) | | | |  __/ |_| | |_) |  __/  __/
|_| |_|\___/|_| |_|\___|\__, |____/ \___|\___|
                        |___/  Node v1.0.0

INFO[...] HoneyBee Node v1.0.0 starting...
INFO[...] Connected to server successfully
INFO[...] Registration accepted
INFO[...] Heartbeat sent

🎉 Success! Your node is connected.

Installation Options

1. System-Wide Installation

# Build the binary
make build

# Install to /usr/local/bin
sudo cp build/honeybee-node /usr/local/bin/
sudo chmod +x /usr/local/bin/honeybee-node

# Verify installation
honeybee-node -version

2. User Installation

# Build the binary
make build

# Install to user bin directory
mkdir -p ~/bin
cp build/honeybee-node ~/bin/
chmod +x ~/bin/honeybee-node

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/bin:$PATH"

# Verify installation
honeybee-node -version

3. Docker Installation

# Build Docker image
cd honeybee_node
docker build -t honeybee-node:latest .

# Run container
docker run -d \
  --name honeybee-node \
  -v $(pwd)/configs/config.yaml:/app/configs/config.yaml \
  honeybee-node:latest

4. Kubernetes Installation

# Apply Kubernetes manifests
kubectl apply -f k8s/

# Check pod status
kubectl get pods -l app=honeybee-node

# View logs
kubectl logs -f -l app=honeybee-node

Verifying Installation

Check Version

honeybee-node -version
# Output: HoneyBee Node v1.0.0

Test Connection

# Start node in foreground
honeybee-node -config configs/config.yaml

# Check logs for:
# ✅ "Connected to server successfully"
# ✅ "Registration accepted"
# ✅ "Heartbeat sent"

Verify Manager Side

On the manager, check logs for:

INFO: Node <id> (<name>) registered from <address>

Configuration Files

After installation, you’ll have:

~/.config/honeybee/
├── .honeybee_totp_secret    # TOTP secret (generated on first run)
└── config.yaml              # Optional user config

/etc/honeybee/               # System-wide (production)
├── config.yaml              # Main configuration
├── certs/                   # TLS certificates
│   ├── ca.crt
│   ├── client.crt
│   └── client.key
└── secrets/                 # TOTP secrets

/var/log/honeybee/           # Logs
└── node.log

Post-Installation

Set Up Security

⚠️ Before production deployment, you must:

  1. ✅ Enable TLS encryption - TLS Setup Guide
  2. ✅ Enable TOTP authentication - TOTP Setup Guide
  3. ✅ Configure firewall rules
  4. ✅ Run as non-root user
  5. ✅ Set up log rotation

See the complete Security Setup Guide.

Configure for Your Environment

Edit your configuration file to match your setup:

node:
  name: "prod-honeypot-01"      # Unique name
  type: "Agent"                  # or "Full"

server:
  address: "manager.example.com:9001"  # Your manager

tls:
  enabled: true                  # ✅ Required
  ca_file: "/etc/honeybee/certs/ca.crt"
  cert_file: "/etc/honeybee/certs/client.crt"
  key_file: "/etc/honeybee/certs/client.key"

auth:
  totp_enabled: true            # ✅ Required

See Configuration Guide for all options.

Set Up as a Service

For production, run as a systemd service:

# Copy service file
sudo cp systemd/honeybee-node.service /etc/systemd/system/

# Enable and start
sudo systemctl enable honeybee-node
sudo systemctl start honeybee-node

# Check status
sudo systemctl status honeybee-node

See Systemd Deployment for details.

Next Steps

  1. ✅ Node installed and running
  2. 📖 Configure your node
  3. 🔐 Set up security
  4. 🚀 Deploy to production

Troubleshooting Installation

Build Fails

# Update Go
go version  # Should be 1.21+

# Clean and rebuild
make clean
make deps
make build

Connection Issues

# Verify manager is running
nc -zv 127.0.0.1 9001

# Check firewall
sudo ufw status

# Test network
ping manager.example.com

Permission Issues

# Fix binary permissions
chmod +x honeybee-node

# Fix config permissions
chmod 644 configs/config.yaml

# Fix TOTP secret directory
chmod 700 ~/.config/honeybee

For more help, see Troubleshooting Guide.

Configuration Guide

Complete reference for configuring your HoneyBee node.

Configuration File

The node uses YAML format for configuration. The default location is configs/config.yaml, but you can specify a different path with the -config flag.

Full Configuration Example

# Node identity and settings
node:
  name: "honeypot-01"
  type: "Agent"
  address: "0.0.0.0"
  port: 8080

# Manager connection settings
server:
  address: "manager.example.com:9001"
  heartbeat_interval: 30
  reconnect_delay: 5
  connection_timeout: 10

# TLS encryption settings
tls:
  enabled: true
  cert_file: "/etc/honeybee/certs/client.crt"
  key_file: "/etc/honeybee/certs/client.key"
  ca_file: "/etc/honeybee/certs/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager"

# Authentication settings
auth:
  totp_enabled: true
  totp_secret_dir: "/var/lib/honeybee/secrets"

# Logging settings
log:
  level: "info"
  format: "json"
  file: "/var/log/honeybee/node.log"

Configuration Sections

Node Settings

node:
  name: "honeypot-01"    # Node identifier
  type: "Agent"          # Node type: "Agent" or "Full"
  address: "0.0.0.0"     # Address to report to manager
  port: 8080             # Port to report to manager

name (string, optional)

Unique identifier for this node. If not specified, defaults to the system hostname.

Examples:

name: "honeypot-01"
name: "edge-sensor-us-east-1"
name: "production-full-node"

Best practices:

  • Use descriptive names
  • Include location or purpose
  • Keep it unique across your deployment

type (string, required)

The type of node determines its capabilities:

TypeDescriptionUse Case
AgentLightweight monitoringEdge deployment, resource-constrained
FullFull honeypot featuresProduction honeypots, interactive deception

Example:

type: "Agent"  # or "Full"

address (string, required)

IP address that this node reports to the manager. This is the address where the node can be reached.

Examples:

address: "0.0.0.0"        # Listen on all interfaces
address: "192.168.1.100"  # Specific internal IP
address: "10.0.0.50"      # Private network IP

port (integer, required)

Port number to report to the manager.

Example:

port: 8080

Server Settings

server:
  address: "manager.example.com:9001"
  heartbeat_interval: 30
  reconnect_delay: 5
  connection_timeout: 10

address (string, required)

Manager server address in host:port format.

Examples:

address: "127.0.0.1:9001"              # Local testing
address: "manager.example.com:9001"   # Production domain
address: "10.0.0.5:9001"               # Internal IP

heartbeat_interval (integer, optional, default: 30)

Seconds between status update heartbeats.

Recommended values:

  • 30 - Default, good for most cases
  • 10-15 - High-availability scenarios
  • 60 - Low-bandwidth environments

Example:

heartbeat_interval: 30  # seconds

reconnect_delay (integer, optional, default: 5)

Seconds to wait before attempting reconnection after connection loss.

Example:

reconnect_delay: 5  # seconds

connection_timeout (integer, optional, default: 10)

Timeout in seconds for initial connection attempts.

Example:

connection_timeout: 10  # seconds

TLS Settings

tls:
  enabled: true
  cert_file: "/path/to/client.crt"
  key_file: "/path/to/client.key"
  ca_file: "/path/to/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager"

enabled (boolean, required)

Enable or disable TLS encryption.

⚠️ Security Warning: Always true in production!

Example:

enabled: true  # Always use true in production

cert_file (string, optional)

Path to client certificate for mutual TLS authentication.

Example:

cert_file: "/etc/honeybee/certs/client.crt"

key_file (string, optional)

Path to client private key for mutual TLS.

Example:

key_file: "/etc/honeybee/certs/client.key"

Note: Both cert_file and key_file must be specified together for mutual TLS.

ca_file (string, optional)

Path to CA certificate for server verification.

Example:

ca_file: "/etc/honeybee/certs/ca.crt"

insecure_skip_verify (boolean, optional, default: false)

Skip TLS certificate verification.

⚠️ Security Warning: Only set to true for local testing!

Example:

insecure_skip_verify: false  # Always false in production

server_name (string, optional)

Expected server name in TLS certificate (for SNI and verification).

Example:

server_name: "honeybee-manager"

Authentication Settings

auth:
  totp_enabled: true
  totp_secret_dir: "/var/lib/honeybee/secrets"

totp_enabled (boolean, required)

Enable TOTP authentication.

⚠️ Security Warning: Always true in production!

Example:

totp_enabled: true  # Always true in production

totp_secret_dir (string, optional)

Directory to store TOTP secret. Defaults to ~/.config/honeybee/.

Examples:

totp_secret_dir: "/var/lib/honeybee/secrets"  # System-wide
totp_secret_dir: "/etc/honeybee/secrets"       # Alternative
# Default: ~/.config/honeybee/

Permissions: Must be readable/writable only by the node user (0700).

Logging Settings

log:
  level: "info"
  format: "json"
  file: "/var/log/honeybee/node.log"

level (string, optional, default: “info”)

Log level controls verbosity.

LevelUse Case
debugDevelopment, troubleshooting
infoNormal production operation
warnOnly warnings and errors
errorOnly errors

Example:

level: "info"  # Recommended for production

format (string, optional, default: “text”)

Log output format.

FormatDescriptionUse Case
textHuman-readableConsole, development
jsonStructured JSONLog aggregation, parsing

Example:

format: "json"  # Recommended for production

file (string, optional)

Path to log file. If not specified, logs go to stdout.

Examples:

file: "/var/log/honeybee/node.log"  # System log directory
file: "./logs/node.log"             # Relative path
# Omit for stdout only

Configuration Validation

The node validates configuration on startup:

# Test configuration
./honeybee-node -config configs/config.yaml

# If valid, you'll see:
INFO: Configuration loaded successfully

# If invalid, you'll see specific error:
ERROR: Invalid configuration: <details>

Environment Variables

Some settings can be overridden with environment variables:

# Override server address
export SERVER_ADDRESS="manager.example.com:9001"

# Run node
./honeybee-node -config configs/config.yaml

Configuration Profiles

Development Profile

node:
  name: "dev-node"
  type: "Agent"

server:
  address: "127.0.0.1:9001"

tls:
  enabled: false  # ⚠️ Testing only!

auth:
  totp_enabled: false  # ⚠️ Testing only!

log:
  level: "debug"
  format: "text"

Production Profile

node:
  name: "prod-honeypot-01"
  type: "Full"
  address: "10.0.1.100"
  port: 8080

server:
  address: "manager.internal.example.com:9001"
  heartbeat_interval: 30
  reconnect_delay: 5
  connection_timeout: 10

tls:
  enabled: true
  cert_file: "/etc/honeybee/certs/client.crt"
  key_file: "/etc/honeybee/certs/client.key"
  ca_file: "/etc/honeybee/certs/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager"

auth:
  totp_enabled: true
  totp_secret_dir: "/var/lib/honeybee/secrets"

log:
  level: "info"
  format: "json"
  file: "/var/log/honeybee/node.log"

Edge Deployment Profile

node:
  name: "edge-sensor-01"
  type: "Agent"
  address: "0.0.0.0"
  port: 8080

server:
  address: "vpn.manager.example.com:9001"
  heartbeat_interval: 60  # Longer interval for bandwidth
  reconnect_delay: 10
  connection_timeout: 30

tls:
  enabled: true
  ca_file: "/etc/honeybee/certs/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager"

auth:
  totp_enabled: true

log:
  level: "warn"  # Minimal logging
  format: "json"
  file: "/var/log/honeybee/node.log"

Security Best Practices

  1. Always enable TLS in production

    tls:
  enabled: true
  insecure_skip_verify: false

  2. Always enable TOTP in production

    auth:
  totp_enabled: true

  3. Use appropriate log levels

    log:
  level: "info"  # Not "debug" in production

  4. Secure file permissions

    chmod 600 /etc/honeybee/config.yaml
chmod 600 /etc/honeybee/certs/*.key
chmod 700 /var/lib/honeybee/secrets

  5. Use strong server names

    tls:
  server_name: "honeybee-manager.internal.example.com"

Next Steps

Node Types

HoneyBee supports two types of nodes: Full and Agent.

Full Node

A Full node provides complete honeypot management capabilities.

Capabilities

  • ✅ Honeypot Installation - Can install honeypots from Potstore or Git repositories
  • ✅ Honeypot Management - Can start, stop, restart, and monitor honeypots
  • ✅ Event Forwarding - Forwards all honeypot events to the Core manager
  • ✅ Status Reporting - Reports honeypot status and health metrics

Configuration

node:
  type: "Full"

honeypot:
  enabled: true  # Required for Full nodes

Use Cases

  • Production deployments
  • Nodes that need to run honeypots
  • Complete honeypot management

Agent Node

An Agent node is a lightweight monitoring probe.

Capabilities

  • ✅ Status Reporting - Reports node health and status
  • ✅ Event Reception - Can receive events from external sources
  • ❌ No Honeypot Management - Cannot install or manage honeypots
  • ❌ No Event Forwarding - Does not forward honeypot events

Configuration

node:
  type: "Agent"

honeypot:
  enabled: false  # Typically disabled for Agent nodes

Use Cases

  • Lightweight monitoring nodes
  • Network probes
  • Status-only reporting
  • Nodes without honeypot requirements

Important Notes

  • Node type is informational - Sent to Core during registration
  • Honeypot management is controlled by honeypot.enabled - Actual capability depends on this setting
  • Core uses node type - Core may use node type to determine which commands to send
  • Default is “Full” - New nodes default to “Full” for maximum capabilities

Choosing a Node Type

Use Full Node When:

  • You need to deploy honeypots
  • You want complete management capabilities
  • You’re deploying in production

Use Agent Node When:

  • You only need status monitoring
  • You want minimal resource usage
  • You’re deploying lightweight probes

Security Setup

Security is paramount for honeypot deployments. This guide walks you through securing your HoneyBee node for production use.

Security Overview

HoneyBee node implements defense-in-depth security:

Layer 1: Network Security (Firewall, VPN)
Layer 2: TLS 1.3 Encryption
Layer 3: Certificate Validation
Layer 4: TOTP Authentication
Layer 5: Application Security

Quick Security Checklist

Before deploying to production:

  • TLS encryption enabled
  • Valid certificates installed
  • Certificate verification enabled (insecure_skip_verify: false)
  • TOTP authentication enabled
  • TOTP secrets secured (0600 permissions)
  • Running as non-root user
  • Firewall configured
  • Log rotation configured
  • Secrets backed up
  • Monitoring enabled

TLS Encryption

Why TLS?

  • Confidentiality: Encrypts all communication
  • Integrity: Prevents tampering
  • Authentication: Verifies server identity
  • Compliance: Meets security standards

Enable TLS

tls:
  enabled: true
  ca_file: "/etc/honeybee/certs/ca.crt"
  cert_file: "/etc/honeybee/certs/client.crt"  # Optional (mutual TLS)
  key_file: "/etc/honeybee/certs/client.key"   # Optional (mutual TLS)
  insecure_skip_verify: false
  server_name: "honeybee-manager"

TLS Configuration

The node uses TLS 1.3 with strong cipher suites:

  • TLS_AES_256_GCM_SHA384
  • TLS_AES_128_GCM_SHA256
  • TLS_CHACHA20_POLY1305_SHA256

See: TLS Setup Guide for detailed instructions.

TOTP Authentication

Why TOTP?

  • Time-based: Codes expire every 30 seconds
  • No shared secrets: Secret never transmitted
  • Standards-based: RFC 6238 compliant
  • Revocable: Easy to reset

Enable TOTP

auth:
  totp_enabled: true
  totp_secret_dir: "/var/lib/honeybee/secrets"

TOTP Workflow

  1. First Connection: Node generates random secret
  2. Registration: Secret used to generate TOTP code
  3. Validation: Manager validates code
  4. Storage: Secret saved for future connections

See: TOTP Setup Guide for detailed instructions.

File Permissions

Configuration Files

# Config file: readable by node user only
chmod 600 /etc/honeybee/config.yaml
chown honeybee:honeybee /etc/honeybee/config.yaml

TLS Certificates

# Private keys: read-only by node user
chmod 600 /etc/honeybee/certs/*.key
chown honeybee:honeybee /etc/honeybee/certs/*.key

# Certificates: readable by all
chmod 644 /etc/honeybee/certs/*.crt

TOTP Secrets

# Secret directory: accessible only by node user
chmod 700 /var/lib/honeybee/secrets
chown honeybee:honeybee /var/lib/honeybee/secrets

# Secret file: read/write by node user only
chmod 600 /var/lib/honeybee/secrets/.honeybee_totp_secret

Log Files

# Log directory
chmod 755 /var/log/honeybee
chown honeybee:honeybee /var/log/honeybee

# Log files
chmod 644 /var/log/honeybee/*.log
chown honeybee:honeybee /var/log/honeybee/*.log

Running as Non-Root

Never run as root! Create a dedicated user:

# Create honeybee user
sudo useradd -r -s /bin/false honeybee

# Create necessary directories
sudo mkdir -p /etc/honeybee /var/lib/honeybee/secrets /var/log/honeybee
sudo chown -R honeybee:honeybee /etc/honeybee /var/lib/honeybee /var/log/honeybee

# Set binary permissions
sudo chown root:root /usr/local/bin/honeybee-node
sudo chmod 755 /usr/local/bin/honeybee-node

Network Security

Firewall Configuration

# Allow outbound to manager only
sudo ufw allow out to 10.0.0.5 port 9001 proto tcp

# Deny all other outbound (optional)
sudo ufw default deny outgoing

# Allow SSH (management)
sudo ufw allow 22/tcp

# Enable firewall
sudo ufw enable

VPN/Tunnel

For additional security, use a VPN or SSH tunnel:

WireGuard Example:

# Install WireGuard
sudo apt install wireguard

# Configure VPN
# /etc/wireguard/wg0.conf

# Connect
sudo wg-quick up wg0

# Configure node to use VPN address
# config.yaml:
# server:
#   address: "10.200.0.1:9001"  # VPN address

Security Hardening

System Hardening

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

# Install security updates automatically
sudo apt install unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

# Enable firewall
sudo ufw enable

# Disable unnecessary services
sudo systemctl disable <service>

Systemd Hardening

Add to /etc/systemd/system/honeybee-node.service:

[Service]
# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/honeybee /var/lib/honeybee
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictRealtime=true
RestrictNamespaces=true

AppArmor Profile

Create /etc/apparmor.d/usr.local.bin.honeybee-node:

#include <tunables/global>

/usr/local/bin/honeybee-node {
  #include <abstractions/base>
  #include <abstractions/nameservice>
  
  /usr/local/bin/honeybee-node r,
  /etc/honeybee/** r,
  /var/lib/honeybee/** rw,
  /var/log/honeybee/** rw,
  
  # Network
  network inet stream,
  network inet6 stream,
  
  # Deny everything else
  /** deny,
}

Monitoring & Auditing

Enable Audit Logging

log:
  level: "info"
  format: "json"  # Easier to parse
  file: "/var/log/honeybee/node.log"

Monitor Security Events

# Watch for failed connections
sudo journalctl -u honeybee-node -f | grep "failed"

# Monitor authentication
sudo tail -f /var/log/honeybee/node.log | grep "authentication"

# Check for errors
sudo tail -f /var/log/honeybee/node.log | grep "ERROR"

Set Up Alerts

Use tools like fail2ban or custom scripts:

# Example: Alert on repeated failures
#!/bin/bash
tail -f /var/log/honeybee/node.log | while read line; do
  if echo "$line" | grep -q "authentication failed"; then
    # Send alert
    echo "Security alert: Authentication failure" | mail -s "HoneyBee Alert" admin@example.com
  fi
done

Backup & Recovery

Backup TOTP Secrets

# Backup secret
sudo cp /var/lib/honeybee/secrets/.honeybee_totp_secret \
       /backup/honeybee/totp_secret_$(date +%Y%m%d).backup

# Encrypt backup
gpg -c /backup/honeybee/totp_secret_$(date +%Y%m%d).backup

Backup Certificates

# Backup certificates
sudo tar czf /backup/honeybee/certs_$(date +%Y%m%d).tar.gz \
       /etc/honeybee/certs/

# Encrypt
gpg -c /backup/honeybee/certs_$(date +%Y%m%d).tar.gz

Recovery

# Restore TOTP secret
sudo cp /backup/honeybee/totp_secret.backup \
       /var/lib/honeybee/secrets/.honeybee_totp_secret
sudo chmod 600 /var/lib/honeybee/secrets/.honeybee_totp_secret
sudo chown honeybee:honeybee /var/lib/honeybee/secrets/.honeybee_totp_secret

# Restore certificates
sudo tar xzf /backup/honeybee/certs.tar.gz -C /

Security Incident Response

If Compromised

  1. Immediate Actions:

    # Stop the node
sudo systemctl stop honeybee-node

# Isolate from network
sudo ufw deny out to manager.example.com port 9001

  2. Investigate:

    # Check logs
sudo journalctl -u honeybee-node --since "1 hour ago"

# Check file changes
sudo find /etc/honeybee -type f -mtime -1

  3. Recovery:

    # Reset TOTP
sudo rm /var/lib/honeybee/secrets/.honeybee_totp_secret

# Regenerate certificates if needed
# (See TLS setup guide)

# Restart with clean state
sudo systemctl start honeybee-node

Security Best Practices Summary

Do’s ✅

  • ✅ Enable TLS encryption
  • ✅ Enable TOTP authentication
  • ✅ Use valid certificates
  • ✅ Run as non-root user
  • ✅ Set proper file permissions
  • ✅ Configure firewall
  • ✅ Monitor logs
  • ✅ Regular backups
  • ✅ Keep software updated
  • ✅ Use strong passwords/secrets

Don’ts ❌

  • ❌ Disable TLS in production
  • ❌ Disable TOTP in production
  • ❌ Skip certificate verification
  • ❌ Run as root
  • ❌ Use weak permissions
  • ❌ Expose to public internet
  • ❌ Ignore security updates
  • ❌ Store secrets in version control
  • ❌ Use default credentials
  • ❌ Disable logging

Security Resources

Compliance

GDPR Considerations

  • Minimize data collection
  • Implement data retention policies
  • Provide audit trails
  • Ensure secure data storage

PCI-DSS Considerations

  • Use strong encryption (TLS 1.3)
  • Implement access controls
  • Monitor and log access
  • Regular security assessments

Next Steps

  1. Set up TLS certificates
  2. Configure TOTP authentication
  3. Deploy securely

TLS Encryption Setup

Complete guide to setting up TLS 1.3 encryption for your HoneyBee node.

Overview

TLS (Transport Layer Security) provides:

  • Encryption: All data encrypted in transit
  • Authentication: Verify server identity
  • Integrity: Detect tampering

The HoneyBee node uses TLS 1.3 with strong cipher suites for maximum security.

TLS Configuration

tls:
  enabled: true
  cert_file: "/etc/honeybee/certs/client.crt"  # Optional
  key_file: "/etc/honeybee/certs/client.key"   # Optional
  ca_file: "/etc/honeybee/certs/ca.crt"        # Recommended
  insecure_skip_verify: false
  server_name: "honeybee-manager"

Certificate Types

The simplest secure setup:

tls:
  enabled: true
  ca_file: "/etc/honeybee/certs/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager"

Use when: You want to verify the server’s identity.

2. Mutual TLS (mTLS) - Maximum Security

Both client and server authenticate each other:

tls:
  enabled: true
  cert_file: "/etc/honeybee/certs/client.crt"
  key_file: "/etc/honeybee/certs/client.key"
  ca_file: "/etc/honeybee/certs/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager"

Use when: Maximum security is required.

3. Development Only (No Certificates)

⚠️ NOT for production!

tls:
  enabled: true
  insecure_skip_verify: true  # Skip verification

Generating Certificates

Option 1: Self-Signed (Development/Testing)

Step 1: Create Certificate Directory

mkdir -p /etc/honeybee/certs
cd /etc/honeybee/certs

Step 2: Generate CA Certificate

# Generate CA private key
openssl genrsa -out ca.key 4096

# Generate CA certificate
openssl req -new -x509 -days 365 -key ca.key -out ca.crt \
  -subj "/C=US/ST=State/L=City/O=HoneyBee/CN=HoneyBee CA"

Step 3: Generate Server Certificate

# Generate server private key
openssl genrsa -out server.key 4096

# Create server certificate signing request
openssl req -new -key server.key -out server.csr \
  -subj "/C=US/ST=State/L=City/O=HoneyBee/CN=honeybee-manager"

# Sign with CA
openssl x509 -req -days 365 -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt

Step 4: Generate Client Certificate (Optional - for mTLS)

# Generate client private key
openssl genrsa -out client.key 4096

# Create client certificate signing request
openssl req -new -key client.key -out client.csr \
  -subj "/C=US/ST=State/L=City/O=HoneyBee/CN=honeybee-node"

# Sign with CA
openssl x509 -req -days 365 -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out client.crt

Step 5: Set Permissions

# Private keys: read-only by owner
chmod 600 *.key

# Certificates: readable by all
chmod 644 *.crt

# Set ownership
chown honeybee:honeybee *

Option 2: Let’s Encrypt (Production)

For production with public domains:

# Install certbot
sudo apt install certbot

# Generate certificate
sudo certbot certonly --standalone \
  -d manager.example.com

# Certificates will be in:
# /etc/letsencrypt/live/manager.example.com/

Configure node:

tls:
  enabled: true
  ca_file: "/etc/letsencrypt/live/manager.example.com/chain.pem"
  server_name: "manager.example.com"

Option 3: Corporate PKI

If using corporate certificates:

  1. Obtain certificates from your CA
  2. Copy to /etc/honeybee/certs/
  3. Configure paths in config.yaml

Verification

Verify Certificate Creation

# Verify CA certificate
openssl x509 -in ca.crt -text -noout

# Verify server certificate
openssl x509 -in server.crt -text -noout

# Verify certificate chain
openssl verify -CAfile ca.crt server.crt

Test TLS Connection

# Test server TLS
openssl s_client -connect 127.0.0.1:9001 -CAfile ca.crt

# Test with client certificate (mTLS)
openssl s_client -connect 127.0.0.1:9001 \
  -CAfile ca.crt \
  -cert client.crt \
  -key client.key

Test with Node

# Run node with TLS
./honeybee-node -config configs/config.yaml

# Check logs for:
# "TLS connection established: version=TLS 1.3"

TLS Configuration Examples

Minimal (CA Only)

tls:
  enabled: true
  ca_file: "/etc/honeybee/certs/ca.crt"
  server_name: "honeybee-manager"

Full (Mutual TLS)

tls:
  enabled: true
  cert_file: "/etc/honeybee/certs/client.crt"
  key_file: "/etc/honeybee/certs/client.key"
  ca_file: "/etc/honeybee/certs/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager.internal.example.com"

Development (Insecure)

tls:
  enabled: true
  insecure_skip_verify: true  # ⚠️ Testing only!

Common Issues

Certificate Verification Failed

Problem: TLS handshake failed: certificate verify failed

Solutions:

  1. Check CA certificate is correct
  2. Verify server name matches certificate CN
  3. Ensure certificate is not expired
  4. Check system time is synchronized
# Check certificate expiry
openssl x509 -in /etc/honeybee/certs/ca.crt -noout -dates

# Sync time
sudo ntpdate -s time.nist.gov

Unknown Authority

Problem: x509: certificate signed by unknown authority

Solutions:

  1. Provide CA certificate in configuration
  2. Or add CA to system trust store
# Add to system trust (Ubuntu/Debian)
sudo cp ca.crt /usr/local/share/ca-certificates/honeybee-ca.crt
sudo update-ca-certificates

Wrong Host Name

Problem: TLS handshake failed: ... certificate is valid for X, not Y

Solutions:

  1. Update server_name in config to match certificate
  2. Or regenerate certificate with correct CN/SAN

Connection Refused

Problem: Connection refused or timeout

Solutions:

  1. Ensure manager has TLS enabled
  2. Check firewall rules
  3. Verify manager is listening on correct port

Certificate Management

Certificate Rotation

Plan certificate rotation before expiry:

# Check expiry
openssl x509 -in server.crt -noout -dates

# Generate new certificates (follow generation steps)

# Update configuration with new paths

# Restart node
sudo systemctl restart honeybee-node

Revocation

If a certificate is compromised:

  1. Generate new certificates
  2. Update all nodes
  3. Restart services
# Generate new CA and certificates
./generate-certs.sh

# Deploy to all nodes
ansible-playbook deploy-certs.yml

# Restart nodes
ansible honeybee-nodes -a "systemctl restart honeybee-node"

Security Best Practices

  1. Never commit private keys to version control

    # Add to .gitignore
echo "*.key" >> .gitignore
echo "*.pem" >> .gitignore

  2. Use strong key sizes

    • Minimum: 2048 bits
    • Recommended: 4096 bits

  3. Regular rotation

    • Certificates: Every 90-365 days
    • CA: Every 1-3 years

  4. Secure storage

    chmod 600 /etc/honeybee/certs/*.key
chmod 700 /etc/honeybee/certs

  5. Use appropriate CN/SAN

    • Match actual hostname/IP
    • Include all aliases

Automation

Certificate Generation Script

#!/bin/bash
# generate-certs.sh

CERT_DIR="/etc/honeybee/certs"
DAYS=365

mkdir -p "$CERT_DIR"
cd "$CERT_DIR"

# CA
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days $DAYS -key ca.key -out ca.crt \
  -subj "/CN=HoneyBee CA"

# Server
openssl genrsa -out server.key 4096
openssl req -new -key server.key -out server.csr \
  -subj "/CN=honeybee-manager"
openssl x509 -req -days $DAYS -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

# Client
openssl genrsa -out client.key 4096
openssl req -new -key client.key -out client.csr \
  -subj "/CN=honeybee-node"
openssl x509 -req -days $DAYS -in client.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt

# Permissions
chmod 600 *.key
chmod 644 *.crt

echo "Certificates generated in $CERT_DIR"

Ansible Playbook

---
- name: Deploy TLS certificates
  hosts: honeybee_nodes
  become: yes
  tasks:
    - name: Create certs directory
      file:
        path: /etc/honeybee/certs
        state: directory
        owner: honeybee
        group: honeybee
        mode: '0700'
    
    - name: Copy CA certificate
      copy:
        src: certs/ca.crt
        dest: /etc/honeybee/certs/ca.crt
        owner: honeybee
        group: honeybee
        mode: '0644'
    
    - name: Copy client certificate
      copy:
        src: "certs/{{ inventory_hostname }}.crt"
        dest: /etc/honeybee/certs/client.crt
        owner: honeybee
        group: honeybee
        mode: '0644'
    
    - name: Copy client key
      copy:
        src: "certs/{{ inventory_hostname }}.key"
        dest: /etc/honeybee/certs/client.key
        owner: honeybee
        group: honeybee
        mode: '0600'
    
    - name: Restart honeybee-node
      systemd:
        name: honeybee-node
        state: restarted

Next Steps

TOTP Authentication Setup

Complete guide to setting up Time-based One-Time Password (TOTP) authentication for your HoneyBee node.

Overview

TOTP provides an additional security layer beyond TLS encryption:

  • Time-based: 6-digit codes valid for 30 seconds
  • No transmission: Secret never sent over network
  • Standard: RFC 6238 compliant
  • Revocable: Easy to reset if compromised

How TOTP Works

First Connection:
1. Node generates random 160-bit secret
2. Node saves secret locally
3. Node generates TOTP code from secret
4. Node sends code with registration
5. Manager validates and stores secret hash

Subsequent Connections:
1. Node loads existing secret
2. Node generates fresh TOTP code
3. Node sends code with registration
4. Manager validates against stored secret

Configuration

auth:
  totp_enabled: true
  totp_secret_dir: "/var/lib/honeybee/secrets"  # Optional

Configuration Options

totp_enabled (required)

Enable or disable TOTP authentication.

⚠️ Always true in production!

totp_enabled: true  # Production
totp_enabled: false # Testing only

totp_secret_dir (optional)

Directory where TOTP secret is stored.

Default: ~/.config/honeybee/

Examples:

totp_secret_dir: "/var/lib/honeybee/secrets"  # System-wide
totp_secret_dir: "/etc/honeybee/secrets"       # Alternative
totp_secret_dir: "~/.honeybee/secrets"         # User directory

First Time Setup

Automatic Setup

TOTP is set up automatically on first connection:

# 1. Enable TOTP in config
# config.yaml:
# auth:
#   totp_enabled: true

# 2. Start node
./honeybee-node -config configs/config.yaml

# The node will:
# - Generate random secret
# - Save to ~/.config/honeybee/.honeybee_totp_secret
# - Generate TOTP code
# - Send to manager for validation

Output:

INFO: Generated new TOTP secret (first-time registration)
INFO: TOTP code generated: 123456
INFO: Connected to server successfully
INFO: Registration accepted

Manual Setup

For advanced use cases:

# 1. Create secret directory
mkdir -p ~/.config/honeybee
chmod 700 ~/.config/honeybee

# 2. Generate secret (160 bits, base32 encoded)
head -c 20 /dev/urandom | base32 > ~/.config/honeybee/.honeybee_totp_secret

# 3. Set permissions
chmod 600 ~/.config/honeybee/.honeybee_totp_secret

# 4. Start node
./honeybee-node -config configs/config.yaml

Secret Storage

File Location

The TOTP secret is stored in:

~/.config/honeybee/.honeybee_totp_secret    # User installation
/var/lib/honeybee/secrets/.honeybee_totp_secret  # System-wide

File Format

Plain text, base32 encoded:

JBSWY3DPEHPK3PXP

Security

Critical: Proper permissions are essential!

# Secret directory: accessible only by node user
chmod 700 /var/lib/honeybee/secrets

# Secret file: read/write only by node user
chmod 600 /var/lib/honeybee/secrets/.honeybee_totp_secret

# Ownership
chown honeybee:honeybee /var/lib/honeybee/secrets
chown honeybee:honeybee /var/lib/honeybee/secrets/.honeybee_totp_secret

Verification

Verify Secret Exists

# Check secret file
ls -la ~/.config/honeybee/.honeybee_totp_secret

# Should show:
# -rw------- 1 user user ... .honeybee_totp_secret

Verify TOTP Generation

The node logs show TOTP usage:

# Run node
./honeybee-node -config configs/config.yaml

# Check logs for:
# "Using existing TOTP secret"
# "TOTP code generated: ******"

Test Authentication

# Start node
./honeybee-node -config configs/config.yaml

# Successful: "Registration accepted"
# Failed: "Registration rejected" or timeout

Resetting TOTP

When to Reset

  • First deployment to new manager
  • Security compromise suspected
  • Lost secret file
  • Testing/development

How to Reset

# 1. Stop node
sudo systemctl stop honeybee-node

# 2. Delete secret
rm ~/.config/honeybee/.honeybee_totp_secret
# or
sudo rm /var/lib/honeybee/secrets/.honeybee_totp_secret

# 3. Start node (will generate new secret)
sudo systemctl start honeybee-node

# 4. Verify in logs
sudo journalctl -u honeybee-node -f
# Look for: "Generated new TOTP secret"

Backup & Recovery

Backup Secret

Critical: Backup your TOTP secrets!

# Backup secret
sudo cp /var/lib/honeybee/secrets/.honeybee_totp_secret \
       /backup/honeybee/totp_$(hostname)_$(date +%Y%m%d).secret

# Encrypt backup (recommended)
gpg -c /backup/honeybee/totp_$(hostname)_$(date +%Y%m%d).secret

# Secure storage
chmod 600 /backup/honeybee/*.secret

Restore Secret

# Decrypt if needed
gpg -d /backup/honeybee/totp_hostname_20240101.secret.gpg > totp.secret

# Restore
sudo cp totp.secret /var/lib/honeybee/secrets/.honeybee_totp_secret

# Set permissions
sudo chmod 600 /var/lib/honeybee/secrets/.honeybee_totp_secret
sudo chown honeybee:honeybee /var/lib/honeybee/secrets/.honeybee_totp_secret

# Restart node
sudo systemctl restart honeybee-node

# Clean up
rm totp.secret

Using with Authenticator Apps

While not required, you can import the secret into authenticator apps for manual verification:

# Generate QR code for authenticator app
qrencode -o totp-qr.png "otpauth://totp/HoneyBee:node-01?secret=$(cat ~/.config/honeybee/.honeybee_totp_secret)&issuer=HoneyBee"

# View QR code
display totp-qr.png

# Or manually enter secret in app
cat ~/.config/honeybee/.honeybee_totp_secret

This allows you to:

  • Generate codes manually
  • Verify code generation
  • Troubleshoot authentication issues

Common Issues

Authentication Failed

Problem: “Registration rejected” or “TOTP authentication failed”

Causes:

  1. Time synchronization issue
  2. Secret mismatch between node and manager
  3. Manager not configured for TOTP

Solutions:

# 1. Check time synchronization
timedatectl status

# 2. Sync time
sudo ntpdate -s time.nist.gov
# or
sudo systemctl restart systemd-timesyncd

# 3. Verify timezone
timedatectl set-timezone UTC

# 4. Reset secret
rm ~/.config/honeybee/.honeybee_totp_secret
./honeybee-node -config configs/config.yaml

Secret Not Found

Problem: Node can’t find TOTP secret file

Solutions:

# 1. Check secret directory exists
mkdir -p ~/.config/honeybee
chmod 700 ~/.config/honeybee

# 2. Check permissions
ls -la ~/.config/honeybee/

# 3. Run node (will generate new secret)
./honeybee-node -config configs/config.yaml

Permission Denied

Problem: Can’t read/write secret file

Solutions:

# Fix ownership
sudo chown -R honeybee:honeybee /var/lib/honeybee/secrets

# Fix permissions
sudo chmod 700 /var/lib/honeybee/secrets
sudo chmod 600 /var/lib/honeybee/secrets/.honeybee_totp_secret

Time Drift

Problem: TOTP codes don’t match due to time difference

Solutions:

# Install NTP
sudo apt install ntp

# Enable time synchronization
sudo systemctl enable ntp
sudo systemctl start ntp

# Force immediate sync
sudo ntpdate -s time.nist.gov

# Verify
timedatectl status

Security Best Practices

1. Secure Storage

# Proper permissions
chmod 700 /var/lib/honeybee/secrets
chmod 600 /var/lib/honeybee/secrets/.honeybee_totp_secret

2. Regular Backups

# Automated backup script
#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR="/backup/honeybee"

mkdir -p "$BACKUP_DIR"
cp /var/lib/honeybee/secrets/.honeybee_totp_secret \
   "$BACKUP_DIR/totp_$DATE.secret"
gpg -c "$BACKUP_DIR/totp_$DATE.secret"
rm "$BACKUP_DIR/totp_$DATE.secret"

3. Encrypted Backups

Always encrypt backups:

gpg -c secret.backup  # Encrypt
gpg -d secret.backup.gpg  # Decrypt

4. Secure Transmission

Never transmit secrets in plain text:

  • Use encrypted channels
  • Use secure key management systems
  • Never commit to version control

5. Rotation Schedule

Rotate secrets periodically:

# Every 90 days (example)
0 0 1 */3 * /usr/local/bin/rotate-totp-secret.sh

6. Audit Access

Monitor secret file access:

# Add audit rule
sudo auditctl -w /var/lib/honeybee/secrets/.honeybee_totp_secret -p rwa

# View audit logs
sudo ausearch -f /var/lib/honeybee/secrets/.honeybee_totp_secret

Multi-Node Deployment

Unique Secrets Per Node

Each node should have its own secret:

# Node 1
./honeybee-node -config node1-config.yaml

# Node 2  
./honeybee-node -config node2-config.yaml

# Each generates its own secret

Centralized Secret Management

For large deployments, use secret management:

HashiCorp Vault Example:

# Store secret in Vault
vault kv put secret/honeybee/node1 totp="JBSWY3DPEHPK3PXP"

# Retrieve in startup script
SECRET=$(vault kv get -field=totp secret/honeybee/node1)
echo "$SECRET" > /var/lib/honeybee/secrets/.honeybee_totp_secret

Monitoring

Log TOTP Events

The node logs TOTP-related events:

# Monitor TOTP usage
sudo journalctl -u honeybee-node -f | grep -i totp

# Common log messages:
# "Generated new TOTP secret"
# "Using existing TOTP secret"
# "TOTP code generated"
# "Registration accepted"

Alert on Failures

# Alert script
#!/bin/bash
tail -f /var/log/honeybee/node.log | while read line; do
  if echo "$line" | grep -q "authentication failed"; then
    echo "TOTP auth failed!" | mail -s "Alert" admin@example.com
  fi
done

Next Steps

Production Deployment Guide

Complete guide for deploying HoneyBee nodes in production environments.

Deployment Options

MethodBest ForComplexityScalability
Standalone BinarySingle server, testingLowLimited
Systemd ServiceLinux serversMediumGood
DockerContainerized environmentsMediumExcellent
KubernetesCloud-native, microservicesHighExcellent
AnsibleFleet managementMediumExcellent

Pre-Deployment Checklist

Before deploying to production:

Security

  • TLS certificates generated and installed
  • TOTP authentication configured
  • Firewall rules configured
  • Running as non-root user
  • Secrets properly secured (0600/0700 permissions)

Configuration

  • Configuration file created and validated
  • Server address configured correctly
  • Log paths created and writable
  • Certificate paths verified

System

  • Time synchronization enabled (NTP)
  • Sufficient disk space for logs
  • Network connectivity to manager verified
  • DNS resolution working (if using hostnames)

Monitoring

  • Log rotation configured
  • Monitoring/alerting set up
  • Backup strategy in place
  • Incident response plan ready

Deployment Methods

Best for: Production Linux servers

Pros:

  • Native Linux service management
  • Automatic start on boot
  • Log integration with journald
  • Easy monitoring and control

Setup:

# 1. Install binary
sudo cp build/honeybee-node /usr/local/bin/
sudo chmod +x /usr/local/bin/honeybee-node

# 2. Create user
sudo useradd -r -s /bin/false honeybee

# 3. Create directories
sudo mkdir -p /etc/honeybee /var/lib/honeybee/secrets /var/log/honeybee
sudo chown -R honeybee:honeybee /var/lib/honeybee /var/log/honeybee

# 4. Copy configuration
sudo cp configs/config.yaml /etc/honeybee/
sudo chown honeybee:honeybee /etc/honeybee/config.yaml
sudo chmod 600 /etc/honeybee/config.yaml

# 5. Install service file
sudo cp systemd/honeybee-node.service /etc/systemd/system/
sudo systemctl daemon-reload

# 6. Enable and start
sudo systemctl enable honeybee-node
sudo systemctl start honeybee-node

# 7. Verify
sudo systemctl status honeybee-node

See: Systemd Deployment Guide for details.

Best for: Containerized environments, cloud deployments

Pros:

  • Isolated environment
  • Easy scaling
  • Portable across platforms
  • Version control

Quick Start:

# Build image
docker build -t honeybee-node:latest .

# Run container
docker run -d \
  --name honeybee-node \
  -v $(pwd)/configs:/app/configs:ro \
  -v $(pwd)/certs:/app/certs:ro \
  -v honeybee-logs:/app/logs \
  -v honeybee-secrets:/home/honeybee/.config/honeybee \
  --restart unless-stopped \
  honeybee-node:latest

See: Docker Deployment Guide for details.

Best for: Cloud-native deployments, microservices

Pros:

  • Automatic scaling
  • Self-healing
  • Rolling updates
  • Service discovery

Quick Start:

# Apply manifests
kubectl apply -f k8s/

# Check status
kubectl get pods -l app=honeybee-node

# View logs
kubectl logs -f -l app=honeybee-node

See: Kubernetes Deployment Guide for details.

4. Standalone Binary

Best for: Testing, development, single deployments

Pros:

  • Simple setup
  • No dependencies
  • Full control

Setup:

# 1. Build
make build

# 2. Configure
cp configs/config.yaml /etc/honeybee/config.yaml

# 3. Run
./build/honeybee-node -config /etc/honeybee/config.yaml

Best for: Managing multiple nodes, automation

Pros:

  • Centralized management
  • Consistent deployment
  • Easy updates
  • Configuration management

Example Playbook:

---
- name: Deploy HoneyBee nodes
  hosts: honeybee_nodes
  become: yes
  
  tasks:
    - name: Install honeybee-node
      copy:
        src: build/honeybee-node
        dest: /usr/local/bin/honeybee-node
        mode: '0755'
    
    - name: Deploy configuration
      template:
        src: config.yaml.j2
        dest: /etc/honeybee/config.yaml
        mode: '0600'
        owner: honeybee
    
    - name: Deploy certificates
      copy:
        src: "certs/{{ inventory_hostname }}/"
        dest: /etc/honeybee/certs/
        mode: '0600'
        owner: honeybee
    
    - name: Start service
      systemd:
        name: honeybee-node
        state: started
        enabled: yes

Configuration Management

Environment-Specific Configs

Create separate configs for each environment:

configs/
├── config.dev.yaml      # Development
├── config.staging.yaml  # Staging
├── config.prod.yaml     # Production
└── config.example.yaml  # Template

Using Templates

Use Go templates or envsubst for dynamic configuration:

# config.template.yaml
server:
  address: "${MANAGER_ADDRESS}"
  
tls:
  ca_file: "${CERT_PATH}/ca.crt"

# Substitute variables
envsubst < config.template.yaml > config.yaml

Secrets Management

HashiCorp Vault

# Store secrets
vault kv put secret/honeybee/node1 \
  totp="JBSWY3DPEHPK3PXP" \
  tls_key="@client.key"

# Retrieve in startup script
vault kv get -field=totp secret/honeybee/node1 > /var/lib/honeybee/secrets/.honeybee_totp_secret

Kubernetes Secrets

apiVersion: v1
kind: Secret
metadata:
  name: honeybee-secrets
type: Opaque
data:
  totp-secret: SkJTV1kzRFBFSFBLM1BYUA==  # base64 encoded

Monitoring & Observability

Logging

Structured Logging (recommended):

log:
  level: "info"
  format: "json"
  file: "/var/log/honeybee/node.log"

Log Aggregation:

  • Elasticsearch + Kibana (ELK)
  • Grafana Loki
  • Splunk
  • CloudWatch (AWS)

Metrics

Future feature - Prometheus metrics endpoint:

metrics:
  enabled: true
  port: 9090

Health Checks

Systemd:

sudo systemctl status honeybee-node

Docker:

docker ps | grep honeybee-node

Kubernetes:

kubectl get pods -l app=honeybee-node

High Availability

Multiple Nodes

Deploy multiple nodes for redundancy:

# Node 1
node:
  name: "honeypot-01"
  address: "10.0.1.10"

# Node 2
node:
  name: "honeypot-02"
  address: "10.0.1.11"

Load Balancing

If using multiple managers (future feature):

server:
  addresses:
    - "manager1.example.com:9001"
    - "manager2.example.com:9001"
  failover: true

Monitoring & Alerting

Set up alerts for:

  • Connection failures
  • Authentication failures
  • High error rates
  • Disk space issues
  • Certificate expiration

Scaling

Horizontal Scaling

Deploy multiple node instances:

Docker Swarm:

docker service create \
  --name honeybee-nodes \
  --replicas 5 \
  honeybee-node:latest

Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: honeybee-node
spec:
  replicas: 5

Resource Allocation

Minimum:

  • CPU: 0.1 cores
  • Memory: 20 MB
  • Disk: 100 MB

Recommended:

  • CPU: 0.25 cores
  • Memory: 50 MB
  • Disk: 500 MB

Updates & Maintenance

Rolling Updates

Zero-downtime updates:

  1. Deploy new version
  2. Test on staging
  3. Roll out gradually
  4. Monitor for issues
  5. Rollback if needed

Kubernetes:

kubectl set image deployment/honeybee-node \
  honeybee-node=honeybee-node:v1.1.0

kubectl rollout status deployment/honeybee-node

Blue-Green Deployment

  1. Deploy new version alongside old
  2. Test new version
  3. Switch traffic to new version
  4. Keep old version for quick rollback

Certificate Rotation

# 1. Generate new certificates
./generate-certs.sh

# 2. Deploy to nodes
ansible-playbook deploy-certs.yml

# 3. Rolling restart
kubectl rollout restart deployment/honeybee-node

Disaster Recovery

Backup Strategy

What to backup:

  • Configuration files
  • TLS certificates
  • TOTP secrets
  • Log archives

Backup script:

#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR="/backup/honeybee/$DATE"

mkdir -p "$BACKUP_DIR"

# Backup config
cp /etc/honeybee/config.yaml "$BACKUP_DIR/"

# Backup certs
tar czf "$BACKUP_DIR/certs.tar.gz" /etc/honeybee/certs/

# Backup secrets
cp /var/lib/honeybee/secrets/.honeybee_totp_secret "$BACKUP_DIR/"

# Encrypt
gpg -c "$BACKUP_DIR"/*

Recovery Procedure

  1. Install honeybee-node
  2. Restore configuration
  3. Restore certificates
  4. Restore TOTP secrets
  5. Start service
  6. Verify connection

Troubleshooting Deployment

Service Won’t Start

# Check service status
sudo systemctl status honeybee-node

# Check logs
sudo journalctl -u honeybee-node -n 50

# Verify configuration
./honeybee-node -config /etc/honeybee/config.yaml

# Check permissions
ls -la /etc/honeybee/config.yaml

Connection Issues

# Test network connectivity
nc -zv manager.example.com 9001

# Test DNS
nslookup manager.example.com

# Check firewall
sudo ufw status

Certificate Issues

# Verify certificates
openssl verify -CAfile /etc/honeybee/certs/ca.crt \
  /etc/honeybee/certs/client.crt

# Check permissions
ls -la /etc/honeybee/certs/

Next Steps

Systemd Service Deployment

Detailed guide for deploying HoneyBee node as a systemd service on Linux.

Overview

Systemd is the standard init system for modern Linux distributions. Running HoneyBee node as a systemd service provides:

  • Automatic start on boot
  • Service management (start/stop/restart)
  • Log integration with journald
  • Resource limits and security hardening
  • Service dependencies
  • Automatic restart on failure

Installation Steps

1. Build the Binary

cd honeybee_node
make build

2. Install Binary

sudo cp build/honeybee-node /usr/local/bin/
sudo chmod +x /usr/local/bin/honeybee-node

3. Create Service User

sudo useradd -r -s /bin/false -d /var/lib/honeybee honeybee

4. Create Directory Structure

sudo mkdir -p /etc/honeybee
sudo mkdir -p /etc/honeybee/certs
sudo mkdir -p /var/lib/honeybee/secrets
sudo mkdir -p /var/log/honeybee

sudo chown -R honeybee:honeybee /etc/honeybee
sudo chown -R honeybee:honeybee /var/lib/honeybee
sudo chown -R honeybee:honeybee /var/log/honeybee

5. Install Configuration

sudo cp configs/config.yaml /etc/honeybee/
sudo chown honeybee:honeybee /etc/honeybee/config.yaml
sudo chmod 600 /etc/honeybee/config.yaml

Edit /etc/honeybee/config.yaml for your environment.

6. Install Certificates

sudo cp certs/*.crt /etc/honeybee/certs/
sudo cp certs/*.key /etc/honeybee/certs/
sudo chown honeybee:honeybee /etc/honeybee/certs/*
sudo chmod 600 /etc/honeybee/certs/*.key
sudo chmod 644 /etc/honeybee/certs/*.crt

7. Create Service File

Create /etc/systemd/system/honeybee-node.service:

[Unit]
Description=HoneyBee Node - Honeypot Agent
Documentation=https://github.com/yourusername/honeybee
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=honeybee
Group=honeybee

ExecStart=/usr/local/bin/honeybee-node -config /etc/honeybee/config.yaml
Restart=on-failure
RestartSec=10s

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/log/honeybee /var/lib/honeybee
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictRealtime=true
RestrictNamespaces=true

# Resource limits
LimitNOFILE=65536
TasksMax=4096

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=honeybee-node

[Install]
WantedBy=multi-user.target

8. Enable and Start Service

sudo systemctl daemon-reload
sudo systemctl enable honeybee-node
sudo systemctl start honeybee-node

9. Verify Service

sudo systemctl status honeybee-node

Service Management

Basic Commands

# Start service
sudo systemctl start honeybee-node

# Stop service
sudo systemctl stop honeybee-node

# Restart service
sudo systemctl restart honeybee-node

# Reload configuration (if supported)
sudo systemctl reload honeybee-node

# Enable auto-start on boot
sudo systemctl enable honeybee-node

# Disable auto-start
sudo systemctl disable honeybee-node

# Check status
sudo systemctl status honeybee-node

# Check if enabled
sudo systemctl is-enabled honeybee-node

# Check if active
sudo systemctl is-active honeybee-node

View Logs

# Follow logs in real-time
sudo journalctl -u honeybee-node -f

# View last 100 lines
sudo journalctl -u honeybee-node -n 100

# View logs since last boot
sudo journalctl -u honeybee-node -b

# View logs for specific time period
sudo journalctl -u honeybee-node --since "1 hour ago"
sudo journalctl -u honeybee-node --since "2024-01-01" --until "2024-01-02"

Advanced Configuration

Service Override

Create custom overrides without modifying main service file:

sudo systemctl edit honeybee-node

This creates /etc/systemd/system/honeybee-node.service.d/override.conf.

Example override:

[Service]
Environment="DEBUG=1"
RestartSec=5s

Resource Limits

Add to service file:

[Service]
# CPU limit (50%)
CPUQuota=50%

# Memory limit
MemoryLimit=512M
MemoryMax=1G

# I/O priority (best-effort, level 4)
IOSchedulingClass=best-effort
IOSchedulingPriority=4

# Process limits
TasksMax=512
LimitNOFILE=65536

Dependencies

Ensure service starts after other services:

[Unit]
After=network-online.target ntp.service
Requires=network-online.target

Troubleshooting

Service Won’t Start

# Check service status
sudo systemctl status honeybee-node

# View full logs
sudo journalctl -u honeybee-node -n 100 --no-pager

# Test configuration
sudo -u honeybee /usr/local/bin/honeybee-node \
  -config /etc/honeybee/config.yaml

# Check file permissions
ls -la /usr/local/bin/honeybee-node
ls -la /etc/honeybee/

Check for Errors

# Check for failed units
systemctl --failed

# Analyze service
systemd-analyze verify honeybee-node.service

# Check for dependency issues
systemctl list-dependencies honeybee-node

Permission Issues

# Verify ownership
sudo chown -R honeybee:honeybee /etc/honeybee
sudo chown -R honeybee:honeybee /var/lib/honeybee
sudo chown -R honeybee:honeybee /var/log/honeybee

# Verify permissions
sudo chmod 700 /var/lib/honeybee/secrets
sudo chmod 600 /etc/honeybee/config.yaml
sudo chmod 600 /etc/honeybee/certs/*.key

Monitoring

Health Check Script

Create /usr/local/bin/honeybee-health-check.sh:

#!/bin/bash

# Check if service is active
if ! systemctl is-active --quiet honeybee-node; then
    echo "CRITICAL: honeybee-node is not running"
    exit 2
fi

# Check recent errors
ERROR_COUNT=$(journalctl -u honeybee-node --since "5 minutes ago" | grep -c ERROR)
if [ "$ERROR_COUNT" -gt 10 ]; then
    echo "WARNING: $ERROR_COUNT errors in last 5 minutes"
    exit 1
fi

echo "OK: honeybee-node is healthy"
exit 0

Timer for Health Checks

Create /etc/systemd/system/honeybee-health-check.timer:

[Unit]
Description=HoneyBee Node Health Check Timer

[Timer]
OnCalendar=*:0/5
Persistent=true

[Install]
WantedBy=timers.target

Log Rotation

Create /etc/logrotate.d/honeybee-node:

/var/log/honeybee/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0644 honeybee honeybee
    postrotate
        systemctl reload honeybee-node > /dev/null 2>&1 || true
    endscript
}

Uninstallation

# Stop and disable service
sudo systemctl stop honeybee-node
sudo systemctl disable honeybee-node

# Remove service file
sudo rm /etc/systemd/system/honeybee-node.service
sudo systemctl daemon-reload

# Remove files
sudo rm /usr/local/bin/honeybee-node
sudo rm -rf /etc/honeybee
sudo rm -rf /var/lib/honeybee
sudo rm -rf /var/log/honeybee

# Remove user
sudo userdel honeybee

Next Steps

Docker Deployment

Guide for deploying HoneyBee node using Docker containers.

Quick Start

# Build image
docker build -t honeybee-node:latest .

# Run container
docker run -d --name honeybee-node honeybee-node:latest

Complete Guide

See the main deployment guide for Docker deployment instructions, including:

  • Docker image building
  • Docker Compose configuration
  • Volume management
  • Network configuration
  • Security hardening
  • Monitoring

Docker Compose Example

version: '3.8'

services:
  honeybee-node:
    image: honeybee-node:latest
    container_name: honeybee-node
    restart: unless-stopped
    volumes:
      - ./configs/config.yaml:/app/configs/config.yaml:ro
      - ./certs:/app/certs:ro
      - honeybee-logs:/app/logs
      - honeybee-secrets:/home/honeybee/.config/honeybee
    environment:
      - TZ=UTC
    networks:
      - honeybee-net

volumes:
  honeybee-logs:
  honeybee-secrets:

networks:
  honeybee-net:
    driver: bridge

For complete Docker deployment instructions, see Deployment Guide.

Windows Service Deployment

Deploy HoneyBee Node as a Windows service.

Prerequisites

  • Windows 7 or later
  • Administrator privileges
  • HoneyBee Node binary (honeybee-node.exe)

Installation Methods

Method 1: NSSM (Non-Sucking Service Manager)

NSSM is the recommended way to install HoneyBee Node as a Windows service.

Install NSSM

  1. Download NSSM from https://nssm.cc/download
  2. Extract to a directory (e.g., C:\nssm)
  3. Add to PATH or use full path

Install Service

# Install service
nssm install HoneyBeeNode "C:\Program Files\HoneyBee\honeybee-node.exe"

# Set parameters
nssm set HoneyBeeNode AppParameters "-config C:\Program Files\HoneyBee\config.yaml"

# Set working directory
nssm set HoneyBeeNode AppDirectory "C:\Program Files\HoneyBee"

# Set description
nssm set HoneyBeeNode Description "HoneyBee Node - Distributed honeypot node"

# Set startup type
nssm set HoneyBeeNode Start SERVICE_AUTO_START

# Set log output
nssm set HoneyBeeNode AppStdout "C:\Program Files\HoneyBee\logs\stdout.log"
nssm set HoneyBeeNode AppStderr "C:\Program Files\HoneyBee\logs\stderr.log"

Start Service

# Start service
nssm start HoneyBeeNode

# Check status
nssm status HoneyBeeNode

Method 2: Windows Service Wrapper

Create a service wrapper using Go or another language (advanced).

Service Management

Start Service

# Using NSSM
nssm start HoneyBeeNode

# Using Windows Service Manager
Start-Service HoneyBeeNode

# Or using sc
sc start HoneyBeeNode

Stop Service

# Using NSSM
nssm stop HoneyBeeNode

# Using Windows Service Manager
Stop-Service HoneyBeeNode

# Or using sc
sc stop HoneyBeeNode

Restart Service

# Using NSSM
nssm restart HoneyBeeNode

# Using Windows Service Manager
Restart-Service HoneyBeeNode

Check Status

# Using NSSM
nssm status HoneyBeeNode

# Using Windows Service Manager
Get-Service HoneyBeeNode

# Or using sc
sc query HoneyBeeNode

Configuration

Place configuration file at:

C:\Program Files\HoneyBee\config.yaml

Ensure the service has read permissions.

Logs

Logs are written to:

C:\Program Files\HoneyBee\logs\

Configure log rotation using Windows Task Scheduler or log management tools.

Troubleshooting

Service Won’t Start

  1. Check Event Viewer for errors
  2. Verify binary path is correct
  3. Check configuration file exists and is valid
  4. Verify user permissions

Service Stops Unexpectedly

  1. Check logs in logs\ directory
  2. Review Event Viewer
  3. Verify Core manager is accessible
  4. Check network connectivity

View Logs

# View stdout
Get-Content "C:\Program Files\HoneyBee\logs\stdout.log" -Tail 50

# View stderr
Get-Content "C:\Program Files\HoneyBee\logs\stderr.log" -Tail 50

Uninstall Service

# Stop service first
nssm stop HoneyBeeNode

# Remove service
nssm remove HoneyBeeNode confirm

Next Steps

Honeypot Management

How HoneyBee Node manages honeypots (pots).

Overview

HoneyBee Node automatically installs, configures, and manages honeypots from the HoneyBee Potstore. Honeypots are installed on-demand via commands from HoneyBee Core.

Installation Flow

  1. Core sends InstallPot command - Specifies honeypot type, ID, and configuration
  2. Node clones Potstore - Downloads honeypot from GitHub
  3. Node sets up environment - Creates virtual environments, installs dependencies
  4. Node configures integration - Sets up event forwarding to Core
  5. Node reports status - Sends installation progress to Core

Supported Honeypots

From the HoneyBee Potstore:

  • Cowrie - SSH and Telnet honeypot (Python/Twisted)
  • HonnyPotter - WordPress login honeypot (PHP)
  • More coming soon…

Installation Process

Automatic Installation

When Core sends an InstallPot command:

{
  "version": 2,
  "message": {
    "NodeCommand": {
      "node_id": 12345,
      "command": {
        "InstallPot": {
          "pot_id": "cowrie-01",
          "honeypot_type": "cowrie",
          "config": {
            "ssh_port": "2222",
            "telnet_port": "2223"
          },
          "auto_start": true
        }
      }
    }
  }
}

The node will:

  1. Clone Potstore repository (if not already cloned)
  2. Copy honeypot to ~/.honeybee/honeypots/cowrie-01/
  3. Create Python virtual environment
  4. Install dependencies (pip install -r requirements.txt)
  5. Configure HoneyBee integration
  6. Start honeypot (if auto_start: true)

Manual Installation

Honeypots can also be installed manually, but automatic installation is recommended.

Honeypot Lifecycle

States

  • Installing - Honeypot is being installed
  • Running - Honeypot is active
  • Stopped - Honeypot is stopped
  • Failed - Installation or startup failed

Commands

Start Honeypot

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "DeployPot": "cowrie-01"
    }
  }
}

Stop Honeypot

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "StopPot": "cowrie-01"
    }
  }
}

Restart Honeypot

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "RestartPot": "cowrie-01"
    }
  }
}

Get Status

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "GetPotStatus": "cowrie-01"
    }
  }
}

Event Forwarding

All honeypot events are automatically forwarded to Core:

  • TCP Socket - Events sent to localhost:9100 (configurable)
  • JSON Format - Structured event data
  • Real-time - Events forwarded immediately

Event Format

{
  "node_id": 12345,
  "pot_id": "cowrie-01",
  "pot_type": "cowrie",
  "event_type": "login",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "username": "admin",
    "password": "password123",
    "ip": "192.168.1.100",
    "session": "abc123"
  }
}

Configuration

Honeypots are configured via the InstallPot command’s config field:

{
  "config": {
    "ssh_port": "2222",
    "telnet_port": "2223",
    "hostname": "honeybee-cowrie",
    "log_path": "/var/log/cowrie"
  }
}

Directory Structure

Honeypots are installed in:

~/.honeybee/honeypots/
├── cowrie-01/          # First Cowrie instance
│   ├── cowrie-env/     # Python virtual environment
│   ├── src/            # Cowrie source
│   ├── etc/            # Configuration
│   └── logs/           # Logs
├── cowrie-02/          # Second Cowrie instance
└── honnypotter-01/     # HonnyPotter instance

Troubleshooting

Installation Fails

  1. Check Python/PHP is installed
  2. Verify Git is available
  3. Check disk space
  4. Review node logs

Honeypot Won’t Start

  1. Check dependencies are installed
  2. Verify configuration
  3. Check port availability
  4. Review honeypot logs

Events Not Forwarding

  1. Verify event listener is running (port 9100)
  2. Check honeypot configuration
  3. Verify network connectivity
  4. Enable debug logging

See Troubleshooting for more help.

Architecture

Technical architecture of the HoneyBee node implementation.

System Architecture

┌─────────────────────────────────────────────────────────┐
│                    HoneyBee Node                        │
├─────────────────────────────────────────────────────────┤
│  cmd/node/main.go                                       │
│  ├── Configuration Loading                              │
│  ├── Logger Initialization                              │
│  ├── Signal Handling                                    │
│  └── Client Lifecycle Management                        │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│              Internal Packages                          │
├─────────────────────────────────────────────────────────┤
│  internal/                                              │
│  ├── client/      (Core client logic)                   │
│  ├── protocol/    (Message definitions)                 │
│  ├── auth/        (TLS & TOTP)                          │
│  ├── config/      (Configuration management)            │
│  └── logger/      (Structured logging)                  │
└─────────────────────────────────────────────────────────┘

Component Details

Client Package

The core client manages:

  • TCP/TLS connection to manager
  • Message serialization/deserialization
  • Heartbeat scheduling
  • Command processing
  • Automatic reconnection

Protocol Package

Defines all Protocol v2 message types:

  • NodeRegistration
  • NodeStatusUpdate
  • NodeEvent
  • NodeCommand
  • RegistrationAck

Auth Package

Handles authentication:

  • TLS: Certificate management, TLS 1.3 configuration
  • TOTP: Secret generation, code generation, storage

Config Package

Configuration management:

  • YAML parsing
  • Validation
  • Default generation
  • Type-safe access

Logger Package

Structured logging:

  • Multiple formats (text/JSON)
  • Configurable levels
  • Field-based logging
  • File and stdout output

Concurrency Model

Main Goroutine: Connection management & lifecycle
  ├── Reader Goroutine: Asynchronous message reading
  ├── Heartbeat Ticker: Periodic status updates
  └── Signal Handler: Graceful shutdown

Security Layers

  1. Network Layer: Firewall, VPN
  2. Transport Layer: TLS 1.3
  3. Authentication Layer: TOTP
  4. Application Layer: Input validation

State Machine

[Start] → [Connecting] → [Registering] → [Running] → [Stopped]
            ↑               ↓                ↓
            └───────────────┴────────────────┘
                    (Reconnect on error)

For more details, see:

Examples

Practical examples for common HoneyBee node use cases.

Basic Examples

Minimal Configuration (Testing Only)

node:
  name: "test-node"
  type: "Agent"
  address: "0.0.0.0"
  port: 8080

server:
  address: "127.0.0.1:9001"

tls:
  enabled: false  # ⚠️ Testing only!

auth:
  totp_enabled: false  # ⚠️ Testing only!

log:
  level: "debug"
  format: "text"

Production Configuration

node:
  name: "prod-honeypot-01"
  type: "Full"
  address: "10.0.1.100"
  port: 8080

server:
  address: "manager.internal:9001"
  heartbeat_interval: 30

tls:
  enabled: true
  cert_file: "/etc/honeybee/certs/client.crt"
  key_file: "/etc/honeybee/certs/client.key"
  ca_file: "/etc/honeybee/certs/ca.crt"
  insecure_skip_verify: false
  server_name: "honeybee-manager"

auth:
  totp_enabled: true
  totp_secret_dir: "/var/lib/honeybee/secrets"

log:
  level: "info"
  format: "json"
  file: "/var/log/honeybee/node.log"

Deployment Examples

Systemd Service

See Systemd Deployment Guide

Docker

See Docker Deployment Guide

Kubernetes

See Kubernetes Deployment Guide

Security Examples

TLS Setup

See TLS Setup Guide

TOTP Setup

See TOTP Setup Guide

More Examples

For comprehensive examples including:

  • Multi-node deployments
  • Ansible playbooks
  • Certificate generation scripts
  • Monitoring configurations
  • Log aggregation

See the complete examples in honeybee_node/docs/EXAMPLES.md.

Troubleshooting Guide

Common issues and solutions for HoneyBee node deployment and operation.

Quick Diagnostic

# Check if node is running
ps aux | grep honeybee-node

# Check service status (systemd)
sudo systemctl status honeybee-node

# View recent logs
sudo journalctl -u honeybee-node -n 100 --no-pager

# Test network connectivity
nc -zv manager.example.com 9001

# Verify certificates
openssl verify -CAfile /etc/honeybee/certs/ca.crt \
  /etc/honeybee/certs/server.crt

Connection Issues

Connection Refused

Symptoms:

  • Connection refused
  • Connection timeout
  • Node can’t reach manager

Causes:

  1. Manager not running
  2. Firewall blocking connection
  3. Incorrect address/port
  4. Network connectivity issue

Solutions:

# 1. Check manager is running
ssh manager-host
ps aux | grep honeybee-core

# 2. Test network connectivity
ping manager.example.com
nc -zv manager.example.com 9001

# 3. Check firewall on node
sudo ufw status
sudo ufw allow out to manager.example.com port 9001

# 4. Check firewall on manager
# (on manager host)
sudo ufw status
sudo ufw allow 9001/tcp

# 5. Verify configuration
cat /etc/honeybee/config.yaml | grep address

Connection Drops Frequently

Symptoms:

  • Frequent reconnections
  • “Connection closed by server”
  • Unstable connection

Causes:

  1. Network instability
  2. Manager restarts
  3. Keepalive not working
  4. Firewall timeout

Solutions:

# 1. Check network quality
ping -c 100 manager.example.com
mtr manager.example.com

# 2. Increase reconnect delay
# config.yaml:
# server:
#   reconnect_delay: 10

# 3. Check manager logs
# (on manager)
sudo journalctl -u honeybee-core -f

# 4. Enable TCP keepalive
# (Usually enabled by default)

TLS Issues

TLS Handshake Failed

Symptoms:

  • TLS handshake failed
  • Certificate verify failed
  • Connection fails after TCP succeeds

Solutions:

# 1. Test TLS connection
openssl s_client -connect manager.example.com:9001 \
  -CAfile /etc/honeybee/certs/ca.crt

# 2. Verify certificate chain
openssl verify -CAfile /etc/honeybee/certs/ca.crt \
  /etc/honeybee/certs/server.crt

# 3. Check certificate expiry
openssl x509 -in /etc/honeybee/certs/ca.crt -noout -dates

# 4. Verify server name matches certificate
openssl x509 -in /etc/honeybee/certs/server.crt -noout -subject

# 5. Check config matches
cat /etc/honeybee/config.yaml | grep server_name

Certificate Signed by Unknown Authority

Symptoms:

  • x509: certificate signed by unknown authority
  • TLS verification fails

Solutions:

# 1. Ensure CA certificate is specified
# config.yaml:
# tls:
#   ca_file: "/etc/honeybee/certs/ca.crt"

# 2. Verify CA certificate file exists
ls -la /etc/honeybee/certs/ca.crt

# 3. Check CA certificate is correct
openssl x509 -in /etc/honeybee/certs/ca.crt -text -noout

# 4. Regenerate if needed
./generate-certs.sh

Certificate Name Mismatch

Symptoms:

  • certificate is valid for X, not Y
  • Server name doesn’t match certificate

Solutions:

# 1. Check certificate CN/SAN
openssl x509 -in /etc/honeybee/certs/server.crt \
  -noout -subject -ext subjectAltName

# 2. Update config to match
# config.yaml:
# tls:
#   server_name: "honeybee-manager"  # Must match certificate

# 3. Or regenerate certificate with correct CN
openssl req -new -key server.key -out server.csr \
  -subj "/CN=correct-hostname"

Authentication Issues

TOTP Authentication Failed

Symptoms:

  • Registration rejected
  • TOTP authentication failed
  • Node can connect but can’t authenticate

Causes:

  1. Time synchronization issue
  2. Secret mismatch
  3. Manager not configured for TOTP

Solutions:

# 1. Check time synchronization
timedatectl status

# 2. Sync time
sudo ntpdate -s time.nist.gov
# or
sudo systemctl restart systemd-timesyncd

# 3. Verify timezone is UTC
timedatectl set-timezone UTC

# 4. Reset TOTP secret
sudo systemctl stop honeybee-node
sudo rm /var/lib/honeybee/secrets/.honeybee_totp_secret
sudo systemctl start honeybee-node

# 5. Check logs for new secret generation
sudo journalctl -u honeybee-node -f | grep TOTP

Time Drift

Symptoms:

  • Intermittent authentication failures
  • Works sometimes, fails other times

Solutions:

# 1. Install NTP
sudo apt install ntp

# 2. Enable time sync
sudo systemctl enable ntp
sudo systemctl start ntp

# 3. Verify time is synchronized
timedatectl status | grep synchronized

# 4. Force sync
sudo ntpdate -s time.nist.gov

# 5. Check time difference
# (both node and manager should be within 30 seconds)

Configuration Issues

Invalid Configuration

Symptoms:

  • Invalid configuration
  • Node won’t start
  • Configuration parse errors

Solutions:

# 1. Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('/etc/honeybee/config.yaml'))"

# 2. Check for required fields
cat /etc/honeybee/config.yaml

# 3. Use example config
cp configs/config.example.yaml /etc/honeybee/config.yaml

# 4. Test configuration
./honeybee-node -config /etc/honeybee/config.yaml

File Not Found

Symptoms:

  • No such file or directory
  • Can’t find certificates, config, etc.

Solutions:

# 1. Check file exists
ls -la /etc/honeybee/config.yaml

# 2. Check permissions
ls -la /etc/honeybee/certs/

# 3. Verify paths in config
cat /etc/honeybee/config.yaml | grep _file

# 4. Create missing directories
sudo mkdir -p /etc/honeybee/certs
sudo mkdir -p /var/lib/honeybee/secrets
sudo mkdir -p /var/log/honeybee

Permission Denied

Symptoms:

  • Permission denied
  • Can’t read/write files

Solutions:

# 1. Check file ownership
ls -la /etc/honeybee/config.yaml

# 2. Fix ownership
sudo chown -R honeybee:honeybee /etc/honeybee
sudo chown -R honeybee:honeybee /var/lib/honeybee
sudo chown -R honeybee:honeybee /var/log/honeybee

# 3. Fix permissions
sudo chmod 600 /etc/honeybee/config.yaml
sudo chmod 600 /etc/honeybee/certs/*.key
sudo chmod 700 /var/lib/honeybee/secrets

# 4. Verify service user
ps aux | grep honeybee-node | grep -v grep

Performance Issues

High CPU Usage

Symptoms:

  • Node using excessive CPU
  • System slowdown

Solutions:

# 1. Check CPU usage
top -p $(pgrep honeybee-node)

# 2. Check for rapid reconnections
sudo journalctl -u honeybee-node | grep "Connecting to server"

# 3. Increase reconnect delay
# config.yaml:
# server:
#   reconnect_delay: 10

# 4. Check for errors causing restart loop
sudo journalctl -u honeybee-node -n 100

High Memory Usage

Symptoms:

  • Node using excessive memory
  • Out of memory errors

Solutions:

# 1. Check memory usage
ps aux | grep honeybee-node

# 2. Check for memory leaks
# (restart and monitor)
sudo systemctl restart honeybee-node
watch -n 1 'ps aux | grep honeybee-node'

# 3. Check log file size
du -h /var/log/honeybee/

# 4. Enable log rotation
# See log rotation section

Disk Space Issues

Symptoms:

  • No space left on device
  • Can’t write logs

Solutions:

# 1. Check disk space
df -h

# 2. Check log file sizes
du -sh /var/log/honeybee/*

# 3. Clean old logs
sudo find /var/log/honeybee -name "*.log.*" -mtime +30 -delete

# 4. Set up log rotation
sudo vi /etc/logrotate.d/honeybee-node

Logging Issues

No Logs Appearing

Symptoms:

  • No log output
  • Log file empty
  • Can’t find logs

Solutions:

# 1. Check log configuration
cat /etc/honeybee/config.yaml | grep -A 3 "^log:"

# 2. Check if logging to file or stdout
# If no file specified, check stdout:
sudo journalctl -u honeybee-node -f

# 3. Check log file permissions
ls -la /var/log/honeybee/

# 4. Create log directory
sudo mkdir -p /var/log/honeybee
sudo chown honeybee:honeybee /var/log/honeybee

# 5. Verify log level
# config.yaml:
# log:
#   level: "debug"  # Temporarily for troubleshooting

Log Rotation Not Working

Symptoms:

  • Log files growing indefinitely
  • Disk space running out

Solutions:

# 1. Check logrotate config
cat /etc/logrotate.d/honeybee-node

# 2. Test logrotate
sudo logrotate -d /etc/logrotate.d/honeybee-node

# 3. Force rotation
sudo logrotate -f /etc/logrotate.d/honeybee-node

# 4. Check logrotate service
sudo systemctl status logrotate.timer

Systemd Issues

Service Won’t Start

Symptoms:

  • Failed to start honeybee-node.service
  • Service immediately stops

Solutions:

# 1. Check service status
sudo systemctl status honeybee-node

# 2. View detailed errors
sudo journalctl -u honeybee-node -n 50 --no-pager

# 3. Check service file
cat /etc/systemd/system/honeybee-node.service

# 4. Verify binary exists
ls -la /usr/local/bin/honeybee-node

# 5. Test binary manually
sudo -u honeybee /usr/local/bin/honeybee-node \
  -config /etc/honeybee/config.yaml

# 6. Reload systemd
sudo systemctl daemon-reload

Service Won’t Stop

Symptoms:

  • Service hangs on stop
  • Has to be killed forcefully

Solutions:

# 1. Check process
ps aux | grep honeybee-node

# 2. Send SIGTERM manually
sudo kill -TERM $(pgrep honeybee-node)

# 3. Wait for graceful shutdown
# Node should send NodeDrop and exit

# 4. If still hung, force kill
sudo kill -9 $(pgrep honeybee-node)

# 5. Check for resource locks
lsof -p $(pgrep honeybee-node)

Debug Mode

Enable debug logging for troubleshooting:

# config.yaml
log:
  level: "debug"
  format: "text"  # Easier to read
  file: "/var/log/honeybee/debug.log"

# Restart with debug logging
sudo systemctl restart honeybee-node

# Watch debug logs
sudo tail -f /var/log/honeybee/debug.log

Getting Help

Collect Diagnostic Information

#!/bin/bash
# collect-diagnostics.sh

echo "=== System Info ==="
uname -a
cat /etc/os-release

echo -e "\n=== Node Status ==="
sudo systemctl status honeybee-node

echo -e "\n=== Recent Logs ==="
sudo journalctl -u honeybee-node -n 100 --no-pager

echo -e "\n=== Configuration ==="
sudo cat /etc/honeybee/config.yaml

echo -e "\n=== Network ==="
nc -zv manager.example.com 9001

echo -e "\n=== Certificates ==="
openssl x509 -in /etc/honeybee/certs/ca.crt -noout -dates

echo -e "\n=== Disk Space ==="
df -h

echo -e "\n=== Permissions ==="
ls -la /etc/honeybee/
ls -la /var/lib/honeybee/
ls -la /var/log/honeybee/

Report Issues

Include:

  1. HoneyBee version
  2. Operating system
  3. Configuration (redact secrets!)
  4. Error messages
  5. Logs (last 100 lines)
  6. Steps to reproduce

Additional Resources

Common Error Messages

ErrorCauseSolution
connection refusedManager not running or firewallCheck manager, test connectivity
TLS handshake failedCertificate issueVerify certificates
x509: certificate signed by unknown authorityMissing CA certAdd ca_file to config
TOTP authentication failedTime driftSync time with NTP
permission deniedWrong file permissionsFix ownership/permissions
config file not foundWrong pathCheck -config flag
invalid configurationConfig syntax errorValidate YAML

Still having issues? Open an issue on GitHub.

HoneyBee Potstore Overview

The HoneyBee Potstore is a repository of pre-configured honeypots ready for deployment via HoneyBee nodes.

What is the Potstore?

The Potstore is a GitHub repository containing:

  • Pre-configured Honeypots: Ready-to-deploy honeypot implementations
  • HoneyBee Integration: All honeypots configured to forward events to nodes
  • Installation Scripts: Automated setup for each honeypot
  • Standardized Format: Consistent structure across all honeypots

Repository

GitHub: https://github.com/H0neyBe/honeybee_potstore

How It Works

  1. Core sends InstallPot command to a node
  2. Node clones Potstore from GitHub
  3. Node installs specified honeypot with dependencies
  4. Node configures HoneyBee integration automatically
  5. Honeypot forwards events to node (port 9100)

Available Honeypots

Currently Available

  • Cowrie - SSH and Telnet honeypot (Python/Twisted)
  • HonnyPotter - WordPress login honeypot (PHP)

Coming Soon

  • Dionaea - Multi-protocol honeypot
  • Heralding - Credential honeypot
  • Elasticpot - Elasticsearch honeypot
  • Mailoney - SMTP honeypot

Potstore Manifest

The potstore.json file contains metadata for all honeypots:

  • Honeypot type and version
  • Requirements (Python, PHP, etc.)
  • Default ports
  • Installation instructions
  • HoneyBee integration details

Directory Structure

honeybee_potstore/
├── README.md
├── LICENSE
├── potstore.json        # Honeypot manifest
├── cowrie/              # Cowrie SSH/Telnet honeypot
│   ├── requirements.txt
│   ├── src/
│   │   └── cowrie/
│   │       └── output/
│   │           └── honeybee.py  # HoneyBee output plugin
│   └── ...
├── HonnyPotter/         # WordPress login honeypot
│   ├── standalone.php
│   ├── honeybee-forwarder.php
│   ├── install.sh
│   └── ...
└── [future-pots]/       # Future honeypots

Next Steps

Available Honeypots

Complete list of honeypots available in the HoneyBee Potstore.

Cowrie

Type: SSH/Telnet Honeypot
Language: Python
Version: 2.9.0
Status: ✅ Stable

Description

Medium to high interaction SSH and Telnet honeypot that logs brute force attacks and shell interaction.

Features

  • SSH honeypot
  • Telnet honeypot
  • Command logging
  • File download tracking
  • Session recording
  • Custom output plugins

Requirements

  • Python 3.7+
  • Linux, Windows, or macOS

Default Ports

  • SSH: 2222
  • Telnet: 2223

Installation

Automatically installed by HoneyBee Node when Core sends InstallPot command.

Configuration

{
  "pot_id": "cowrie-01",
  "honeypot_type": "cowrie",
  "config": {
    "ssh_port": "2222",
    "telnet_port": "2223"
  }
}

HoneyBee Integration

  • Output plugin: src/cowrie/output/honeybee.py
  • Events forwarded to: localhost:9100
  • Format: JSON (one event per line)

HonnyPotter

Type: WordPress Login Honeypot
Language: PHP
Version: 1.2.0
Status: ✅ Stable

Description

WordPress login honeypot that captures brute-force attacks and credential stuffing attempts.

Features

  • WordPress login emulation
  • XML-RPC endpoint support
  • Brute-force attack detection
  • Credential logging
  • Low resource usage
  • No database required
  • Standalone or WordPress plugin mode

Requirements

  • PHP 7.4+
  • PHP extensions: json, sockets
  • Linux, Windows, or macOS

Default Ports

  • HTTP: 80
  • HTTPS: 443

Installation

Automatically installed by HoneyBee Node when Core sends InstallPot command.

Configuration

{
  "pot_id": "honnypotter-01",
  "honeypot_type": "honnypotter",
  "config": {
    "http_port": "8080"
  }
}

HoneyBee Integration

  • Forwarder: honeybee-forwarder.php
  • Events forwarded to: localhost:9100
  • Format: JSON

Usage Modes

  1. Standalone: Run standalone.php directly
  2. WordPress Plugin: Install as WordPress plugin

Coming Soon

Dionaea

Multi-protocol honeypot supporting FTP, HTTP, SMB, MySQL, and more.

Heralding

Credential honeypot that captures authentication attempts.

Elasticpot

Elasticsearch honeypot for detecting Elasticsearch attacks.

Mailoney

SMTP honeypot for capturing email-based attacks.

Honeypot Comparison

HoneypotTypeProtocolsLanguageStatus
CowrieSSH/TelnetSSH, TelnetPython✅ Stable
HonnyPotterWebHTTP, HTTPSPHP✅ Stable
DionaeaMultiFTP, HTTP, SMB, MySQLC🚧 Planned
HeraldingCredentialMultiplePython🚧 Planned
ElasticpotSearchHTTPPython🚧 Planned
MailoneyEmailSMTPPython🚧 Planned

Next Steps

Using Honeypots

How to deploy and use honeypots from the HoneyBee Potstore.

Automatic Installation

Honeypots are automatically installed when Core sends an InstallPot command to a node.

Example: Install Cowrie

{
  "version": 2,
  "message": {
    "NodeCommand": {
      "node_id": 12345,
      "command": {
        "InstallPot": {
          "pot_id": "cowrie-01",
          "honeypot_type": "cowrie",
          "config": {
            "ssh_port": "2222",
            "telnet_port": "2223"
          },
          "auto_start": true
        }
      }
    }
  }
}

The node will:

  1. Clone Potstore repository
  2. Install Cowrie with dependencies
  3. Configure HoneyBee integration
  4. Start Cowrie automatically

Manual Installation

You can also install honeypots manually for testing:

Cowrie

# Clone Potstore
git clone https://github.com/H0neyBe/honeybee_potstore.git
cd honeybee_potstore/cowrie

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install -r requirements.txt

# Configure HoneyBee output
# Edit etc/cowrie.cfg to enable honeybee.py output plugin

# Start Cowrie
bin/cowrie start

HonnyPotter

# Clone Potstore
git clone https://github.com/H0neyBe/honeybee_potstore.git
cd honeybee_potstore/HonnyPotter

# Run installation script
chmod +x install.sh
./install.sh

# Start PHP server
php -S 0.0.0.0:8080 standalone.php

Managing Honeypots

Start Honeypot

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "DeployPot": "cowrie-01"
    }
  }
}

Stop Honeypot

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "StopPot": "cowrie-01"
    }
  }
}

Restart Honeypot

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "RestartPot": "cowrie-01"
    }
  }
}

Check Status

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "GetPotStatus": "cowrie-01"
    }
  }
}

Configuration

Honeypots are configured via the config field in InstallPot:

Cowrie Configuration

{
  "config": {
    "ssh_port": "2222",
    "telnet_port": "2223",
    "hostname": "honeybee-cowrie",
    "log_path": "/var/log/cowrie"
  }
}

HonnyPotter Configuration

{
  "config": {
    "http_port": "8080",
    "pot_id": "honnypotter-01"
  }
}

Event Monitoring

Once honeypots are running, they forward events to the node, which forwards them to Core.

View Events

Events can be viewed via:

  • Core logs
  • Backend API (port 9002)
  • WebSocket proxy (port 9003)

Event Format

See Event Format for event structure.

Testing Honeypots

Test Cowrie

# SSH to honeypot
ssh -p 2222 admin@localhost

# Or Telnet
telnet localhost 2223

Test HonnyPotter

# Test login endpoint
curl -X POST http://localhost:8080/standalone.php \
  -d "log=admin&pwd=password123"

Troubleshooting

Installation Fails

  1. Check Python/PHP is installed
  2. Verify Git is available
  3. Check disk space
  4. Review node logs

Honeypot Won’t Start

  1. Check dependencies are installed
  2. Verify configuration
  3. Check port availability
  4. Review honeypot logs

Events Not Forwarding

  1. Verify event listener is running (port 9100)
  2. Check honeypot configuration
  3. Verify network connectivity
  4. Enable debug logging

Next Steps

Adding New Honeypots

Guide for adding new honeypots to the HoneyBee Potstore.

Requirements

To add a honeypot to the Potstore, it must:

  1. ✅ Be installable (Python: pip install, PHP: standalone or composer)
  2. ✅ Support Python 3.7+ or PHP 7.4+
  3. ✅ Send events to TCP socket localhost:9100
  4. ✅ Use JSON format for events (one per line)
  5. ✅ Include installation instructions
  6. ✅ Include HoneyBee integration code

Directory Structure

Create a directory for your honeypot:

honeybee_potstore/
└── your-honeypot/
    ├── README.md              # Honeypot documentation
    ├── install.sh             # Installation script (Linux/macOS)
    ├── install.ps1            # Installation script (Windows)
    ├── requirements.txt       # Python dependencies (if Python)
    ├── honeybee-integration/  # HoneyBee integration code
    └── ...

HoneyBee Integration

Python Honeypots

Create an output plugin or integration module:

# honeybee-integration/honeybee.py
import json
import socket
import os

def send_event(event_data):
    """Send event to HoneyBee Node"""
    port = int(os.getenv('HONEYBEE_EVENT_PORT', '9100'))
    pot_id = os.getenv('HONEYBEE_POT_ID', 'honeypot-01')
    
    event = {
        "pot_id": pot_id,
        "event_type": event_data.get("event_type"),
        "timestamp": event_data.get("timestamp"),
        "data": event_data
    }
    
    try:
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.connect(('localhost', port))
        sock.sendall((json.dumps(event) + '\n').encode())
        sock.close()
    except Exception as e:
        print(f"Failed to send event: {e}")

PHP Honeypots

Create a forwarder script:

<?php
// honeybee-forwarder.php
function sendToHoneyBee($eventData) {
    $port = (int)($_ENV['HONEYBEE_EVENT_PORT'] ?? 9100);
    $potId = $_ENV['HONEYBEE_POT_ID'] ?? 'honeypot-01';
    
    $event = [
        'pot_id' => $potId,
        'event_type' => $eventData['event_type'],
        'timestamp' => date('c'),
        'data' => $eventData
    ];
    
    $socket = @fsockopen('localhost', $port, $errno, $errstr, 1);
    if ($socket) {
        fwrite($socket, json_encode($event) . "\n");
        fclose($socket);
    }
}
?>

Installation Scripts

install.sh (Linux/macOS)

#!/bin/bash
set -e

echo "Installing Your Honeypot..."

# Create directories
mkdir -p logs

# Install dependencies (example for Python)
if [ -f "requirements.txt" ]; then
    pip install -r requirements.txt
fi

# Set permissions
chmod +x your-honeypot.py

echo "Installation complete!"

install.ps1 (Windows)

Write-Host "Installing Your Honeypot..."

# Create directories
New-Item -ItemType Directory -Force -Path logs

# Install dependencies
if (Test-Path "requirements.txt") {
    pip install -r requirements.txt
}

Write-Host "Installation complete!"

Update potstore.json

Add your honeypot to potstore.json:

{
  "id": "your-honeypot",
  "name": "Your Honeypot",
  "version": "1.0.0",
  "type": "your-honeypot",
  "description": "Description of your honeypot",
  "protocols": ["protocol1", "protocol2"],
  "default_ports": {
    "protocol1": 2222
  },
  "requirements": {
    "python": ">=3.7",
    "os": ["linux", "windows", "macos"]
  },
  "directory": "your-honeypot",
  "setup": {
    "install": "./install.sh",
    "output_plugin": "honeybee-integration/honeybee.py"
  },
  "status": "stable",
  "features": [
    "Feature 1",
    "Feature 2"
  ],
  "honeybee_integration": {
    "event_port": 9100,
    "event_format": "json",
    "output_plugin": "honeybee.py",
    "auto_configure": true
  }
}

Event Format

Events must follow this structure:

{
  "pot_id": "your-honeypot-01",
  "event_type": "your.event.type",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    // Event-specific data
  }
}

Testing

  1. Install your honeypot manually
  2. Configure HoneyBee integration
  3. Start honeypot
  4. Generate test events
  5. Verify events are sent to localhost:9100
  6. Check events are received by node

Submission

  1. Fork the Potstore repository
  2. Add your honeypot directory
  3. Update potstore.json
  4. Create a pull request
  5. Include documentation and examples

Next Steps

HoneyBee Integration

Technical guide for integrating honeypots with HoneyBee.

Overview

Honeypots integrate with HoneyBee by sending events to the HoneyBee Node, which forwards them to the Core manager.

Event Flow

Honeypot → Node (TCP:9100) → Core (Protocol v2)

Integration Methods

Method 1: Output Plugin (Python)

For Python honeypots, create an output plugin:

# honeybee.py
import json
import socket
import os
from datetime import datetime

class HoneyBeeOutput:
    def __init__(self):
        self.port = int(os.getenv('HONEYBEE_EVENT_PORT', '9100'))
        self.pot_id = os.getenv('HONEYBEE_POT_ID', 'honeypot-01')
        self.pot_type = os.getenv('HONEYBEE_HONEYPOT_TYPE', 'honeypot')
    
    def send_event(self, event_type, data):
        event = {
            "pot_id": self.pot_id,
            "pot_type": self.pot_type,
            "event_type": event_type,
            "timestamp": datetime.utcnow().isoformat() + "Z",
            "data": data
        }
        
        try:
            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
            sock.connect(('localhost', self.port))
            sock.sendall((json.dumps(event) + '\n').encode())
            sock.close()
        except Exception as e:
            print(f"Failed to send event to HoneyBee: {e}")
    
    def start(self):
        # Called when honeypot starts
        self.send_event("honeypot.started", {})
    
    def stop(self):
        # Called when honeypot stops
        self.send_event("honeypot.stopped", {})

Method 2: Forwarder Script (PHP)

For PHP honeypots, create a forwarder:

<?php
// honeybee-forwarder.php
class HoneyBeeForwarder {
    private $port;
    private $potId;
    private $potType;
    
    public function __construct() {
        $this->port = (int)($_ENV['HONEYBEE_EVENT_PORT'] ?? 9100);
        $this->potId = $_ENV['HONEYBEE_POT_ID'] ?? 'honeypot-01';
        $this->potType = $_ENV['HONEYBEE_HONEYPOT_TYPE'] ?? 'honeypot';
    }
    
    public function sendEvent($eventType, $data) {
        $event = [
            'pot_id' => $this->potId,
            'pot_type' => $this->potType,
            'event_type' => $eventType,
            'timestamp' => date('c'),
            'data' => $data
        ];
        
        $socket = @fsockopen('localhost', $this->port, $errno, $errstr, 1);
        if ($socket) {
            fwrite($socket, json_encode($event) . "\n");
            fclose($socket);
            return true;
        }
        return false;
    }
}
?>

Environment Variables

HoneyBee Node sets these environment variables for honeypots:

  • HONEYBEE_EVENT_PORT - Port to send events to (default: 9100)
  • HONEYBEE_POT_ID - ID of the honeypot instance
  • HONEYBEE_HONEYPOT_TYPE - Type of honeypot

Event Format

Events must be JSON, one per line:

{"pot_id":"cowrie-01","pot_type":"cowrie","event_type":"login","timestamp":"2024-01-15T10:30:00Z","data":{"username":"admin"}}
{"pot_id":"cowrie-01","pot_type":"cowrie","event_type":"command","timestamp":"2024-01-15T10:30:01Z","data":{"input":"ls"}}

Connection Handling

  • Protocol: TCP
  • Address: localhost
  • Port: 9100 (configurable)
  • Format: JSON lines (one event per line)
  • Error Handling: Fail silently, don’t block honeypot

Best Practices

  1. Non-blocking: Don’t block honeypot if connection fails
  2. Error Handling: Log errors but continue operation
  3. Batching: Send events immediately (real-time)
  4. Format: Always use JSON, one event per line
  5. Timestamps: Use ISO 8601 format with Z timezone

Testing Integration

Test Event Sending

import socket
import json

event = {
    "pot_id": "test-01",
    "pot_type": "test",
    "event_type": "test.event",
    "timestamp": "2024-01-15T10:30:00Z",
    "data": {"test": "data"}
}

sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(('localhost', 9100))
sock.sendall((json.dumps(event) + '\n').encode())
sock.close()

Verify Events Received

Check node logs to verify events are received and forwarded to Core.

Next Steps

Protocol v2 Specification

HoneyBee Protocol v2 is the communication protocol between HoneyBee Core and HoneyBee Nodes.

Overview

  • Transport: TCP with optional TLS 1.3
  • Format: JSON messages wrapped in versioned envelopes
  • Version: 2
  • Bidirectional: Both Core and Node can initiate messages

Message Envelope

All messages are wrapped in a versioned envelope:

{
  "version": 2,
  "message": {
    // Message content
  }
}

Protocol Version

Current protocol version is 2. Version is included in every message envelope.

Message Types

Node → Core Messages

NodeRegistration

Register a new node with the Core.

{
  "version": 2,
  "message": {
    "NodeRegistration": {
      "node_id": 12345,
      "node_name": "my-node",
      "address": "0.0.0.0",
      "port": 8080,
      "node_type": "Full",
      "totp_code": "123456"
    }
  }
}

NodeStatusUpdate

Update node status.

{
  "version": 2,
  "message": {
    "NodeStatusUpdate": {
      "node_id": 12345,
      "status": "Running"
    }
  }
}

PotStatusUpdate

Update honeypot (pot) status.

{
  "version": 2,
  "message": {
    "PotStatusUpdate": {
      "node_id": 12345,
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "status": "Running",
      "message": "Honeypot started successfully"
    }
  }
}

PotEvent

Honeypot event (attack data).

{
  "version": 2,
  "message": {
    "PotEvent": {
      "node_id": 12345,
      "pot_id": "cowrie-01",
      "event_type": "login",
      "timestamp": "2024-01-15T10:30:00Z",
      "data": {
        "username": "admin",
        "password": "password123",
        "ip": "192.168.1.100"
      }
    }
  }
}

Core → Node Messages

RegistrationAck

Registration acknowledgment.

{
  "version": 2,
  "message": {
    "RegistrationAck": {
      "accepted": true,
      "message": "Registration successful",
      "totp_key": "BASE32SECRET"  // Only on first registration
    }
  }
}

NodeCommand

Command to node.

{
  "version": 2,
  "message": {
    "NodeCommand": {
      "node_id": 12345,
      "command": {
        "InstallPot": {
          "pot_id": "cowrie-01",
          "honeypot_type": "cowrie",
          "config": {
            "ssh_port": "2222"
          },
          "auto_start": true
        }
      }
    }
  }
}

Node Status Values

  • Connected - Node is connected
  • Deploying - Node is being deployed
  • Running - Node is active
  • Stopped - Node is stopped
  • Failed - Node encountered an error
  • Unknown - Status cannot be determined

Pot Status Values

  • Installing - Honeypot is being installed
  • Running - Honeypot is active
  • Stopped - Honeypot is stopped
  • Failed - Installation or startup failed

Node Types

  • Full - Full-featured honeypot node
  • Agent - Lightweight monitoring agent

Commands

See Command Reference for all available commands.

Events

See Event Format for event structure and types.

Security

TLS Encryption

Optional TLS 1.3 encryption for all communication.

TOTP Authentication

Time-based one-time password for node registration.

Next Steps

Message Types

Complete reference for all HoneyBee Protocol v2 message types.

Message Envelope

All messages are wrapped in a versioned envelope:

{
  "version": 2,
  "message": {
    // One of the message types below
  }
}

Node → Core Messages

NodeRegistration

Register a new node with the Core.

Fields:

  • node_id (uint64) - Unique node identifier
  • node_name (string) - Human-readable node name
  • address (string) - Node’s reported address
  • port (uint16) - Node’s reported port
  • node_type (string) - “Full” or “Agent”
  • totp_code (string, optional) - TOTP code for authentication

Example:

{
  "version": 2,
  "message": {
    "NodeRegistration": {
      "node_id": 12345,
      "node_name": "my-node",
      "address": "0.0.0.0",
      "port": 8080,
      "node_type": "Full",
      "totp_code": "123456"
    }
  }
}

NodeStatusUpdate

Update node status.

Fields:

  • node_id (uint64) - Node identifier
  • status (string) - Status: “Connected”, “Deploying”, “Running”, “Stopped”, “Failed”, “Unknown”

Example:

{
  "version": 2,
  "message": {
    "NodeStatusUpdate": {
      "node_id": 12345,
      "status": "Running"
    }
  }
}

PotStatusUpdate

Update honeypot (pot) status.

Fields:

  • node_id (uint64) - Node identifier
  • pot_id (string) - Honeypot instance ID
  • pot_type (string) - Honeypot type (cowrie, honnypotter, etc.)
  • status (string) - Status: “Installing”, “Running”, “Stopped”, “Failed”
  • message (string, optional) - Status message

Example:

{
  "version": 2,
  "message": {
    "PotStatusUpdate": {
      "node_id": 12345,
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "status": "Running",
      "message": "Honeypot started successfully"
    }
  }
}

PotEvent

Honeypot event (attack data).

Fields:

  • node_id (uint64) - Node identifier
  • pot_id (string) - Honeypot instance ID
  • pot_type (string) - Honeypot type
  • event_type (string) - Event type
  • timestamp (string) - ISO 8601 timestamp
  • data (object) - Event-specific data

Example:

{
  "version": 2,
  "message": {
    "PotEvent": {
      "node_id": 12345,
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "event_type": "login",
      "timestamp": "2024-01-15T10:30:00Z",
      "data": {
        "username": "admin",
        "password": "password123",
        "ip": "192.168.1.100"
      }
    }
  }
}

NodeEvent

General node event.

Fields:

  • type (string) - Event type: “Started”, “Stopped”, “Error”
  • message (string, optional) - Event message

Example:

{
  "version": 2,
  "message": {
    "NodeEvent": {
      "type": "Started",
      "message": "Node started successfully"
    }
  }
}

NodeDrop

Notify Core that node is disconnecting.

Fields: None

Example:

{
  "version": 2,
  "message": {
    "NodeDrop": {}
  }
}

Core → Node Messages

RegistrationAck

Registration acknowledgment.

Fields:

  • accepted (bool) - Whether registration was accepted
  • message (string, optional) - Acknowledgment message
  • totp_key (string, optional) - TOTP secret key (only on first registration)

Example:

{
  "version": 2,
  "message": {
    "RegistrationAck": {
      "accepted": true,
      "message": "Registration successful",
      "totp_key": "BASE32SECRET"
    }
  }
}

NodeCommand

Command to node.

Fields:

  • node_id (uint64) - Target node identifier
  • command (object) - Command object (see Command Reference)

Example:

{
  "version": 2,
  "message": {
    "NodeCommand": {
      "node_id": 12345,
      "command": {
        "InstallPot": {
          "pot_id": "cowrie-01",
          "honeypot_type": "cowrie",
          "auto_start": true
        }
      }
    }
  }
}

Message Ordering

Messages are sent in order, but Core and Node can send messages concurrently.

Error Handling

If a message is invalid or cannot be processed:

  1. Log the error
  2. Send error response (if applicable)
  3. Continue operation (don’t disconnect)

Next Steps

Command Reference

Complete reference for all HoneyBee Protocol v2 commands.

InstallPot

Install a honeypot from Potstore or custom Git repository.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "InstallPot": {
        "pot_id": "cowrie-01",
        "honeypot_type": "cowrie",
        "git_url": null,  // null = use Potstore
        "git_branch": null,  // null = use default branch
        "config": {
          "ssh_port": "2222",
          "telnet_port": "2223"
        },
        "auto_start": true
      }
    }
  }
}

Response: Node sends PotStatusUpdate with status changes.

DeployPot

Start a honeypot instance.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "DeployPot": "cowrie-01"
    }
  }
}

Response: Node sends PotStatusUpdate with new status.

StopPot

Stop a honeypot instance.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "StopPot": "cowrie-01"
    }
  }
}

Response: Node sends PotStatusUpdate with new status.

RestartPot

Restart a honeypot instance.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "RestartPot": "cowrie-01"
    }
  }
}

Response: Node sends PotStatusUpdate with status changes.

GetPotStatus

Get current status of a honeypot.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "GetPotStatus": "cowrie-01"
    }
  }
}

Response: Node sends PotStatusUpdate with current status.

GetInstalledPots

Get list of all installed honeypots on a node.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "GetInstalledPots": {}
    }
  }
}

Response: Node sends multiple PotStatusUpdate messages, one for each honeypot.

GetPotInfo

Get detailed information about a honeypot.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "GetPotInfo": "cowrie-01"
    }
  }
}

Response: Node sends PotStatusUpdate with detailed information.

Restart

Restart the node.

{
  "NodeCommand": {
    "node_id": 12345,
    "command": {
      "Restart": {}
    }
  }
}

Response: Node sends NodeStatusUpdate with status changes.

Command Execution Flow

  1. Core sends NodeCommand to node
  2. Node processes command
  3. Node sends status updates as command progresses
  4. Node sends final status update when complete

Error Handling

If a command fails, the node sends a status update with status: "Failed" and an error message in the message field.

Next Steps

Event Format

Honeypot events forwarded from nodes to Core.

Event Structure

Events are sent as PotEvent messages:

{
  "version": 2,
  "message": {
    "PotEvent": {
      "node_id": 12345,
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "event_type": "login",
      "timestamp": "2024-01-15T10:30:00Z",
      "data": {
        // Event-specific data
      }
    }
  }
}

Event Types

Cowrie Events

Login Attempt

{
  "event_type": "cowrie.login.success",
  "data": {
    "username": "admin",
    "password": "password123",
    "src_ip": "192.168.1.100",
    "src_port": 54321,
    "dst_port": 2222,
    "session": "abc123"
  }
}

Command Execution

{
  "event_type": "cowrie.command.input",
  "data": {
    "input": "ls -la",
    "session": "abc123",
    "src_ip": "192.168.1.100"
  }
}

File Download

{
  "event_type": "cowrie.session.file_download",
  "data": {
    "url": "http://example.com/malware.sh",
    "outfile": "/tmp/malware.sh",
    "session": "abc123",
    "src_ip": "192.168.1.100"
  }
}

HonnyPotter Events

Login Attempt

{
  "event_type": "honnypotter.login.failed",
  "data": {
    "username": "admin",
    "password": "password123",
    "ip": "192.168.1.100",
    "user_agent": "Mozilla/5.0",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

XML-RPC Attack

{
  "event_type": "honnypotter.xmlrpc.attack",
  "data": {
    "method": "wp.getUsersBlogs",
    "username": "admin",
    "password": "password123",
    "ip": "192.168.1.100"
  }
}

Event Forwarding

From Honeypot to Node

Honeypots send events to node via TCP socket:

  • Port: 9100 (configurable via HONEYBEE_EVENT_PORT)
  • Format: JSON (one event per line)
  • Protocol: TCP

From Node to Core

Nodes forward events to Core via Protocol v2:

  • Message Type: PotEvent
  • Format: JSON in Protocol v2 envelope
  • Protocol: TCP/TLS with Protocol v2

Event Flow

Honeypot → Node (TCP:9100) → Core (Protocol v2)

Timestamps

All events include ISO 8601 timestamps:

2024-01-15T10:30:00Z

Event Metadata

All events include:

  • node_id - ID of the node
  • pot_id - ID of the honeypot instance
  • pot_type - Type of honeypot (cowrie, honnypotter, etc.)
  • event_type - Type of event
  • timestamp - When the event occurred
  • data - Event-specific data

Next Steps

Configuration Reference

Complete configuration reference for all HoneyBee components.

HoneyBee Core Configuration

File: bee_config.toml

[server]
host = "127.0.0.1"        # Bind address
node_port = 9001         # Port for node connections
backend_port = 9002      # Port for backend API
debug = false            # Enable debug mode

[logging]
level = "debug"          # Log level: trace, debug, info, warn, error
folder = "logs"          # Log directory
force_color = true       # Force colored output

[proxy]
enabled = true           # Enable WebSocket proxy
host = "0.0.0.0"        # Proxy bind address
port = 9003             # Proxy port

HoneyBee Node Configuration

File: configs/config.yaml

node:
  name: "honeybee-node-01"  # Unique node identifier
  type: "Full"              # "Full" or "Agent"
  address: "0.0.0.0"        # Address to report
  port: 8080                # Port to report

server:
  address: "127.0.0.1:9001"  # Core manager address
  heartbeat_interval: 30     # Heartbeat interval (seconds)
  reconnect_delay: 5         # Reconnect delay (seconds)
  connection_timeout: 10      # Connection timeout (seconds)

tls:
  enabled: true               # Enable TLS encryption
  insecure_skip_verify: false # Skip certificate verification
  server_name: "honeybee-manager"  # Server name for TLS
  cert_file: ""              # Client certificate (optional)
  key_file: ""               # Client key (optional)
  ca_file: ""                # CA certificate (optional)

auth:
  totp_enabled: true         # Enable TOTP authentication
  totp_secret_dir: ""        # TOTP secret directory (optional)

log:
  level: "info"              # Log level: debug, info, warn, error
  format: "text"             # Log format: text or json
  file: ""                   # Log file path (optional)

honeypot:
  enabled: true              # Enable honeypot management
  base_dir: "~/.honeybee/honeypots"  # Honeypot installation directory
  default_ssh_port: 2222     # Default SSH port
  default_telnet_port: 2223  # Default Telnet port

Environment Variables

HoneyBee Node

  • HONEYBEE_EVENT_PORT - Port for honeypot events (default: 9100)
  • HONEYBEE_POT_ID - Honeypot instance ID
  • HONEYBEE_HONEYPOT_TYPE - Honeypot type

HoneyBee Core

  • RUST_LOG - Rust logging level (default: info)

Configuration Validation

Both Core and Node validate configuration on startup. Invalid configuration will cause the component to exit with an error.

Next Steps

API Reference

HoneyBee Core Backend API reference.

Base URL

http://localhost:9002

Endpoints

Health Check

Check if Core is running.

GET /health

Response:

{
  "status": "ok"
}

Get Nodes

Get list of all registered nodes.

GET /api/v1/nodes

Response:

{
  "nodes": [
    {
      "node_id": 12345,
      "node_name": "my-node",
      "status": "Running",
      "node_type": "Full"
    }
  ]
}

Get Node Status

Get status of a specific node.

GET /api/v1/nodes/{node_id}

Response:

{
  "node_id": 12345,
  "node_name": "my-node",
  "status": "Running",
  "node_type": "Full",
  "honeypots": [
    {
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "status": "Running"
    }
  ]
}

Get Honeypots

Get list of all honeypots across all nodes.

GET /api/v1/honeypots

Response:

{
  "honeypots": [
    {
      "node_id": 12345,
      "pot_id": "cowrie-01",
      "pot_type": "cowrie",
      "status": "Running"
    }
  ]
}

WebSocket Proxy

Real-time updates via WebSocket on port 9003.

Connect: ws://localhost:9003

Messages: JSON Protocol v2 messages

Authentication

API authentication is planned for future versions.

Rate Limiting

Rate limiting is planned for future versions.

Next Steps

Error Codes

Reference for error codes and messages.

Node Errors

Connection Errors

  • CONNECTION_FAILED - Failed to connect to Core
  • TLS_HANDSHAKE_FAILED - TLS handshake failed
  • REGISTRATION_FAILED - Node registration failed
  • AUTHENTICATION_FAILED - TOTP authentication failed

Configuration Errors

  • CONFIG_READ_FAILED - Failed to read configuration file
  • CONFIG_PARSE_FAILED - Failed to parse configuration
  • CONFIG_INVALID - Configuration validation failed
  • EMPTY_NODE_NAME - Node name cannot be empty
  • INVALID_NODE_TYPE - Invalid node type (must be “Full” or “Agent”)
  • EMPTY_SERVER_ADDR - Server address is required

Honeypot Errors

  • HONEYPOT_NOT_FOUND - Honeypot not found
  • HONEYPOT_ALREADY_EXISTS - Honeypot already exists
  • HONEYPOT_INSTALL_FAILED - Honeypot installation failed
  • HONEYPOT_START_FAILED - Failed to start honeypot
  • HONEYPOT_STOP_FAILED - Failed to stop honeypot

Core Errors

Node Management Errors

  • NODE_NOT_FOUND - Node not found
  • NODE_ALREADY_REGISTERED - Node already registered
  • INVALID_NODE_ID - Invalid node ID

Command Errors

  • COMMAND_FAILED - Command execution failed
  • INVALID_COMMAND - Invalid command type
  • COMMAND_TIMEOUT - Command execution timeout

Protocol Errors

  • PROTOCOL_VERSION_MISMATCH - Protocol version mismatch
  • INVALID_MESSAGE_FORMAT - Invalid message format
  • MESSAGE_PARSE_FAILED - Failed to parse message

Error Response Format

Errors are returned in status updates:

{
  "status": "Failed",
  "message": "Error description"
}

Troubleshooting

See Troubleshooting Guide for common errors and solutions.

Building from Source

Build HoneyBee components from source.

HoneyBee Core

Prerequisites

  • Rust 1.75+ (nightly toolchain)
  • Cargo

Build Steps

# Clone repository
git clone https://github.com/H0neyBe/honeybee_core.git
cd honeybee_core

# Install Rust nightly
rustup toolchain install nightly
rustup default nightly

# Build
cargo build --release

# Binary location
target/release/honeybee_core

Build with Features

# Build with tracing support
cargo build --release --features tracing

HoneyBee Node

Prerequisites

  • Go 1.21+

Build Steps

# Clone repository
git clone https://github.com/H0neyBe/honeybee_node.git
cd honeybee_node

# Build
make build

# Or manually
go build -o build/honeybee-node ./cmd/node

Cross-Platform Builds

# Linux
make build-linux

# Windows
make build-windows

# macOS
make build-darwin

# All platforms
make build-all

HoneyBee Potstore

No build required - it’s a repository of honeypots.

Development Mode

Core

# Run with debug logging
RUST_LOG=debug cargo run

# Run with tracing
cargo run --features tracing

Node

# Run in development mode
make dev

# Or manually
go run ./cmd/node -config configs/config.yaml -debug

Next Steps

Contributing to HoneyBee

Thank you for your interest in contributing to HoneyBee!

How to Contribute

Reporting Issues

  • Use GitHub Issues for bug reports
  • Include steps to reproduce
  • Provide logs and error messages
  • Specify component (Core, Node, Potstore)

Submitting Code

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Code Style

  • Rust (Core): Follow Rust standard formatting (rustfmt)
  • Go (Node): Follow Go standard formatting (gofmt)
  • Documentation: Use Markdown, follow existing style

Component-Specific Guidelines

HoneyBee Core

  • Follow Rust best practices
  • Use async/await (Tokio)
  • Add tests for new features
  • Update documentation

HoneyBee Node

  • Follow Go best practices
  • Use structured logging
  • Add error handling
  • Update configuration docs

HoneyBee Potstore

  • Follow existing honeypot structure
  • Include installation scripts
  • Add HoneyBee integration
  • Update potstore.json

Testing

  • Run existing tests before submitting
  • Add tests for new features
  • Test on multiple platforms if applicable

Documentation

  • Update relevant documentation
  • Add examples for new features
  • Keep documentation in sync with code

Next Steps

Creating Custom Nodes

Build HoneyBee nodes in any language.

Overview

HoneyBee nodes can be implemented in any language that supports:

  • TCP sockets
  • JSON parsing
  • TLS (optional)

Protocol Requirements

Your node must implement:

  1. Connect to Core - TCP connection to Core (port 9001)
  2. Register - Send NodeRegistration message
  3. Handle Commands - Process NodeCommand messages
  4. Send Status - Send NodeStatusUpdate periodically
  5. Send Events - Send PotEvent messages (if managing honeypots)

Implementation Steps

1. Connect to Core

import socket
import ssl

# Connect to Core
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

# Optional: Wrap with TLS
if use_tls:
    context = ssl.create_default_context()
    sock = context.wrap_socket(sock, server_hostname="honeybee-manager")

sock.connect(("localhost", 9001))

2. Register Node

import json

registration = {
    "version": 2,
    "message": {
        "NodeRegistration": {
            "node_id": 12345,
            "node_name": "my-python-node",
            "address": "0.0.0.0",
            "port": 8080,
            "node_type": "Full",
            "totp_code": "123456"  # If TOTP enabled
        }
    }
}

message = json.dumps(registration) + "\n"
sock.sendall(message.encode())

3. Handle Messages

while True:
    data = sock.recv(4096)
    if not data:
        break
    
    message = json.loads(data.decode())
    
    if "RegistrationAck" in message["message"]:
        ack = message["message"]["RegistrationAck"]
        if ack["accepted"]:
            print("Registration successful")
    
    elif "NodeCommand" in message["message"]:
        command = message["message"]["NodeCommand"]
        handle_command(command)

4. Send Heartbeat

import time

while True:
    status_update = {
        "version": 2,
        "message": {
            "NodeStatusUpdate": {
                "node_id": 12345,
                "status": "Running"
            }
        }
    }
    
    message = json.dumps(status_update) + "\n"
    sock.sendall(message.encode())
    
    time.sleep(30)  # Every 30 seconds

Example Implementations

Python

See example Python node (if available in repository).

Rust

See example Rust node (if available in repository).

Protocol Details

See Protocol Specification for complete protocol details.

Next Steps

Testing Guide

Testing HoneyBee components.

Testing HoneyBee Core

Unit Tests

cd honeybee_core
cargo test

Integration Tests

# Run with test configuration
cargo test --test integration

Testing HoneyBee Node

Unit Tests

cd honeybee_node
make test

Integration Tests

# Test with mock Core
go test ./internal/... -v

Testing Honeypots

Test Cowrie

# Install Cowrie
cd honeybee_potstore/cowrie
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Start Cowrie
bin/cowrie start

# Test SSH connection
ssh -p 2222 admin@localhost

Test HonnyPotter

# Start PHP server
cd honeybee_potstore/HonnyPotter
php -S 0.0.0.0:8080 standalone.php

# Test login
curl -X POST http://localhost:8080/standalone.php \
  -d "log=admin&pwd=password123"

End-to-End Testing

  1. Start HoneyBee Core
  2. Start HoneyBee Node
  3. Verify node registration
  4. Install honeypot
  5. Generate test attack
  6. Verify event forwarding

Next Steps

HoneyBee: A Modular Honeypot Orchestration Framework for Network Security Enhancement

technologies used

rust (core)

The core component is written in Rust. It is responsible for:

  • Managing network connections to and from agents.
  • Managing network connections to and from the inferfaces (modular extensions)
  • Providing an interface for higher-level system control (via the dashboard backend).

The modular system is designed to allow extensions in any language and can later be enhanced with modules to add extra features.

go (agents)

they are the part that interact with the honypot machine directly They will:

  • Expose control interfaces to the core for managing nodes.
  • Report activity, telemetry, and captured data back to the core.
  • Optionally extend functionality by utilizing unused ports or aggregating data from multiple devices in agent mode (office devices can be used as honeypots with no operational downsides).

Two types of agents are planned:

  1. Full Nodes — fully controllable honeypot nodes managed directly by the orchestrator.
  2. Extension Nodes — lightweight agents that run alongside existing services to monitor unused ports, detect anomalies, or collect passive intelligence.

extension modules (backends)

modules can be written in any language that can do TCP, and they will have the full interface available to them:

  • Extend core functionality dynamically.
  • Be loadable and unloadable at runtime.
  • Provide features such as advanced analytics and automation.

go (backend)

The backend acts as a translation layer between the frontend and the Rust core, in core its a extension module. It provides:

  • A REST or WebSocket API for dashboard communication.
  • A secure bridge between user interactions and core orchestration logic.

js framework (frontend)

The frontend dashboard provides users with:

  • Real-time visualization of nodes and system health.
  • Control interfaces for deployment, plugin management, and orchestration tasks.
  • Access to alerts, analytics, and reports generated by the system.

architecture

flowchart LR
	subgraph backend_thread["Backen_thread"]
        Backend_manager["Backend_manager"]
	end
  subgraph Node_thread["Node manager"]
        Node_manager["Node manager"]
	end
  
	subgraph master["master orchestrator node"]
        core["core"]
        Backend_manager["Backend manager"]
        backend_thread
        Node_thread
	end
	subgraph normal_node["normal_node"]
        agent["agent"]
	end
	subgraph nodes["nodes"]
        full_node["full_node"]
        normal_node
	end
	subgraph module["modules"]
		direction LR
		    py_module["Python module"]
		    rs_module["Rust module"]
		end
	subgraph dashboard["dashboard (extenstion module)"]
        backend["backend"]
        frontend["frontend"]
	end

    Node_manager <--> core  
    core <--> Backend_manager  

    frontend <--> backend
    Backend_manager <--> backend
    Backend_manager <--> py_module & rs_module  

    full_node & agent <--> Node_manager