HoneyAegis: Build Your Own AI-Powered Honeypot Network

The Hacker's Path: Companion Guide

This pairs with Part 1: Introduction and Part 2: Flipper Mastery. You've learned offense. Now build your defense.

I priced out commercial honeypot platforms last month. Thinkst Canary wants $5,000/year for five devices. Other vendors charge per sensor, per month, with your threat data flowing through their infrastructure first. They see your attackers before you do.

That's insane.

A honeypot is a decoy system designed to be attacked. You deploy fake services—SSH, SMB, FTP—and watch what happens. Attackers think they're breaking into a real server, but they're actually handing you intelligence about their tools, techniques, and targets. It's offensive defense.

The concept is simple. The implementation shouldn't cost a mortgage payment.

So we built HoneyAegis: a self-hosted, Docker-native honeypot platform with local AI analysis. A Raspberry Pi 5 runs the sensors. An old Alienware laptop runs the brains. Everything stays on your network. No cloud. No subscriptions. No vendor seeing your threat data before you do.

Deploy in an afternoon. Own everything forever.

What Is a Honeypot?

Before we build, let's clarify what we're building.

A honeypot is a deliberately vulnerable system deployed to attract attackers. It looks real enough to fool automated scanners and curious hackers, but it's entirely fake. There's no real data, no real users, no real services—just emulated ones that log everything.

Why would you want one?

• Early warning: Attackers hit your honeypot before your real systems. You see them coming.
• Threat intelligence: Learn what tools they use, what credentials they try, what they're after.
• Attack patterns: Build a database of techniques specific to your network's exposure.
• Training: Watch real attacks unfold. Better than any simulation.
• Penetration testing: A safe target for your own offensive exercises.

What HoneyAegis Emulates

Cowrie: SSH and Telnet honeypot. Records full session transcripts, captures credentials, logs commands.

Dionaea: Captures malware. Emulates SMB, FTP, HTTP, and other services. Stores payloads for analysis.

OpenCanary: Multi-service honeypot. Emulates Windows shares, MySQL, SSH, and more. Highly configurable.

The Two-Node Architecture

HoneyAegis uses a deliberate split: the sensor faces the internet, the brain stays protected.

1Internet ──► Router (port forward) ──► Pi 5 SENSOR
2                                           │
3                                           │ Vector (logs)
4                                           ▼
5Internal Network ◄──────► Alienware BRAIN
6                              │
7                              ├── PostgreSQL + TimescaleDB
8                              ├── FastAPI Backend
9                              ├── Ollama (local AI)
10                              ├── Next.js Dashboard
11                              └── Redis + Celery

Why separate them?

The sensor is intentionally exposed. It will be attacked. That's the entire point. If something goes catastrophically wrong—if an attacker escapes the honeypot containers—the Pi is a $60 device with nothing on it except decoys. Wipe it. Redeploy. Thirty minutes.

The brain contains everything valuable: your database, your dashboard, your AI analysis, your historical attack data. It never touches the internet. It sits on your internal network, receiving logs from the sensor over a secure channel.

⚠️ The Brain Never Faces the Internet

Port forwarding to the brain is instant compromise. The brain has your PostgreSQL database, your API, your dashboard. Expose it and you've invited attackers to your actual infrastructure. Only the sensor gets port forwarded. Only honeypot ports. Nothing else.

Hardware Configuration

Here's what we're running. This isn't the only valid configuration—it's our optimal setup using hardware we already had.

NODE 1 — SENSOR (Raspberry Pi 5 4GB)

NODE 2 — BRAIN (Alienware 15 R3)

Why the GTX 1070?

Local AI requires GPU acceleration to be useful. The GTX 1070 has 8GB VRAM—enough to run Ollama with llama3.1:8b comfortably. This gives you AI-generated threat summaries without sending data to OpenAI or Anthropic. The AI explains what attackers are doing in plain English, entirely on your hardware.

Step-by-Step Setup: Pi 5 Sensor

Let's build this from bare metal. We'll start with the sensor—the Pi 5 that faces the internet.

Phase 1: Raspberry Pi 5 Sensor Setup

Time: 45 minutes

Prerequisites: Raspberry Pi 5 (4GB), microSD card or NVMe HAT, power supply, Ethernet cable, another computer with SSH

1.1 Flash Raspberry Pi OS

Download Raspberry Pi Imager on your computer. Insert your microSD card.

1# In Raspberry Pi Imager:
2# 1. Choose Device: Raspberry Pi 5
3# 2. Choose OS: Raspberry Pi OS Lite (64-bit)
4# 3. Choose Storage: Your microSD card
5# 4. Click the gear icon for advanced options:
6#    - Set hostname: honeypot-sensor
7#    - Enable SSH with password authentication
8#    - Set username/password (not pi/raspberry)
9#    - Configure WiFi if needed (but use Ethernet)
10# 5. Write the image

Insert the card into your Pi 5, connect Ethernet, and power on.

1.2 Initial Configuration

SSH into your Pi:

1# From your computer
2ssh [email protected]
3
4# Update everything
5sudo apt update && sudo apt upgrade -y
6
7# Install essential tools
8sudo apt install -y git curl vim htop

1.3 Set a Static IP

Your Pi needs a predictable IP for port forwarding. Replace the IP addresses with your network's scheme:

1# Check your current connection name
2nmcli con show
3
4# Set static IP (adjust for your network)
5sudo nmcli con mod "Wired connection 1" ipv4.addresses 192.168.1.50/24
6sudo nmcli con mod "Wired connection 1" ipv4.gateway 192.168.1.1
7sudo nmcli con mod "Wired connection 1" ipv4.dns "8.8.8.8,8.8.4.4"
8sudo nmcli con mod "Wired connection 1" ipv4.method manual
9sudo nmcli con up "Wired connection 1"
10
11# Verify
12ip addr show eth0

1.4 Install Docker

1# Install Docker using the convenience script
2curl -fsSL https://get.docker.com -o get-docker.sh
3sudo sh get-docker.sh
4
5# Add your user to the docker group
6sudo usermod -aG docker $USER
7
8# Install Docker Compose plugin
9sudo apt install -y docker-compose-plugin
10
11# Log out and back in for group changes
12exit
13
14# SSH back in, then verify
15docker --version
16docker compose version

1.5 Deploy HoneyAegis Sensor

1# Clone the repository
2git clone https://github.com/thesecretchief/HoneyAegis.git
3cd HoneyAegis
4
5# Copy environment template
6cp .env.example .env
7
8# Edit configuration
9nano .env

In the .env file, set these values:

1# Sensor configuration
2HONEYAEGIS_MODE=sensor
3BRAIN_HOST=192.168.1.100  # Your Alienware's IP
4SENSOR_NAME=pi5-sensor-01

Deploy the sensor stack:

1# Start sensor services
2docker compose --profile sensor up -d
3
4# Watch the containers come up
5docker ps
6# Expected containers:
7# - honeyaegis-cowrie (SSH/Telnet honeypot)
8# - honeyaegis-dionaea (malware capture)
9# - honeyaegis-opencanary (multi-service)
10# - honeyaegis-vector (log shipper)
11
12# Check logs to verify everything's working
13docker compose logs -f

Step-by-Step Setup: Alienware Brain

Now the brain—the protected node that processes everything.

Phase 2: Alienware Brain Setup

Time: 30 minutes

Prerequisites: Kali Linux installed, NVIDIA drivers configured, connected to same network as Pi

2.1 Verify Kali and NVIDIA

1# Check Kali version
2cat /etc/os-release
3
4# Verify NVIDIA driver is working
5nvidia-smi
6# You should see:
7# - Driver version (535+ recommended)
8# - GTX 1070 with ~8GB VRAM
9# - CUDA version

2.2 Install Docker on Kali

1# Update and install Docker
2sudo apt update
3sudo apt install -y docker.io docker-compose-v2
4
5# Enable and start Docker
6sudo systemctl enable docker
7sudo systemctl start docker
8
9# Add your user to docker group
10sudo usermod -aG docker $USER
11
12# Log out and back in, then verify
13docker --version
14docker compose version

2.3 Install NVIDIA Container Toolkit

This lets Docker containers access your GPU—required for Ollama:

1# Add NVIDIA container toolkit repository
2distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
3curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
4curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
5  sudo tee /etc/apt/sources.list.d/nvidia-docker.list
6
7# Install the toolkit
8sudo apt update
9sudo apt install -y nvidia-container-toolkit
10
11# Configure Docker to use NVIDIA runtime
12sudo nvidia-ctk runtime configure --runtime=docker
13sudo systemctl restart docker
14
15# Test GPU access in a container
16docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

2.4 Deploy HoneyAegis Brain

1# Clone the repository
2git clone https://github.com/thesecretchief/HoneyAegis.git
3cd HoneyAegis
4
5# Copy environment template
6cp .env.example .env
7
8# Edit configuration
9nano .env

Configure the brain:

1# Brain configuration
2HONEYAEGIS_MODE=brain
3OLLAMA_GPU=true
4POSTGRES_PASSWORD=your-strong-password-here
5JWT_SECRET=another-strong-secret
6ADMIN_PASSWORD=dashboard-admin-password

Deploy:

1# Start the full brain stack
2docker compose --profile brain up -d
3
4# This takes a few minutes on first run
5# Watch progress:
6docker compose logs -f
7
8# Once containers are up, pull the AI model
9docker exec -it honeyaegis-ollama ollama pull llama3.1:8b
10# This downloads ~4.7GB - takes a few minutes
11
12# Verify all containers
13docker ps
14# Expected containers:
15# - honeyaegis-fastapi (API backend)
16# - honeyaegis-postgres (database)
17# - honeyaegis-redis (cache/queue)
18# - honeyaegis-celery (background workers)
19# - honeyaegis-ollama (local AI)
20# - honeyaegis-nextjs (dashboard)
21# - honeyaegis-traefik (reverse proxy)

Network Configuration

This is where people screw up. Read carefully.

⚠️ Port Forwarding Rules

ONLY forward these ports to the Pi sensor:

NEVER forward these:

• Port 3000 (Dashboard)
• Port 8000 (API)
• Port 5432 (PostgreSQL)
• Port 6379 (Redis)
• Any port to the Alienware

Log into your router and configure port forwarding to the Pi's static IP (192.168.1.50 in our example). The honeypot services run on high ports internally, but attackers see them on standard ports externally.

Accessing the Dashboard

From any computer on your internal network:

1# Open in browser:
2http://192.168.1.100:3000
3
4# Default credentials (change immediately!):
5# Username: admin
6# Password: (what you set in ADMIN_PASSWORD)

What you'll see:

• Real-time attack feed: Live stream of incoming attacks as they happen
• GeoIP map: Visual representation of where attacks originate
• Session recordings: Full transcripts of SSH/Telnet sessions, exportable as MP4/GIF
• AI summaries: Ollama-generated explanations of attack patterns in plain English
• Statistics: Attack frequency, common credentials, targeted services
• Alerts configuration: Set up Slack, Discord, email notifications via Apprise

Using HoneyAegis for Penetration Testing

Here's where it gets fun. Your honeypot is a safe target for practicing offensive techniques.

Exercise: Attack Your Own Honeypot

From Kali (targeting the Pi's internal IP):

1. Run nmap against the Pi to see exposed services
2. Attempt SSH brute force with Hydra
3. Try SMB enumeration
4. Watch the dashboard light up in real-time
5. Read the AI's analysis of your attack

1# Scan your honeypot
2nmap -sV -p 22,23,445,21 192.168.1.50
3
4# Brute force SSH (Cowrie will accept anything and log it)
5hydra -l root -P /usr/share/wordlists/rockyou.txt ssh://192.168.1.50:2222
6
7# Connect manually and poke around
8ssh [email protected] -p 2222
9# Try common passwords - Cowrie accepts them
10
11# Check the dashboard - your session appears instantly
12# Watch the AI explain what you did

Integration with The Hacker's Path:

• Part 3 (Kali Fundamentals): Use your honeypot as a reconnaissance target
• Part 4 (Exploitation): Practice Metasploit against your controlled environment
• Part 5 (Full Audit): Include honeypot deployment as a defensive component

What About Home Assistant on the Same Pi?

Short answer: Don't do it.

⚠️ Keep Your Honeypot Isolated

Your honeypot sensor is intentionally exposed to the internet. It will be attacked—that's the entire point. Running Home Assistant on the same device puts your smart home controls one container escape away from attackers. If something goes wrong, you want the blast radius limited to fake services, not your actual door locks and thermostat. Use a separate Pi for Home Assistant.

The good news? That ~1.5 GB of headroom isn't wasted. HoneyAegis has room to grow.

Better Uses for Your Pi's Capacity

Instead of cramming unrelated services onto an exposed device, use that headroom for deeper honeypot capabilities:

Pi 5 4GB RAM Budget (Dedicated Sensor)

Roadmap: Coming to HoneyAegis

We're actively developing additional sensor modules for the HoneyAegis GitHub project. Planned additions include:

• Conpot (~200 MB) — Industrial control system honeypot. Emulates PLCs and SCADA systems.
• Mailoney (~100 MB) — SMTP honeypot. Captures spam bots and credential harvesters.
• Elasticpot (~150 MB) — Elasticsearch honeypot. Catches bots scanning for exposed clusters.
• ADBHoney (~100 MB) — Android Debug Bridge honeypot. Detects mobile-targeting attackers.
• Honey tokens — Fake AWS credentials and API keys that trigger alerts when used.

The architecture is built for this. HoneyAegis uses a modular Docker Compose structure—each new honeypot drops in as a container with Vector shipping its logs to the brain. Star the repo to follow development, or contribute your own modules.

The principle: Keep your honeypot sensor doing one thing well—being an attractive, isolated target that feeds intelligence to your brain. Run Home Assistant on a separate device where it belongs.

Related reading: Operation Smart Home covers dedicated Home Assistant setups, and Your WiFi Can See You Moving explains WiFi sensing on its own hardware.

Troubleshooting & Maintenance

1# View logs (both nodes)
2docker compose logs -f
3docker compose logs -f service-name
4
5# Restart a service
6docker compose restart cowrie
7
8# Check container resource usage
9docker stats
10
11# Database backup (on brain)
12docker exec honeyaegis-postgres pg_dump -U honeyaegis honeyaegis > backup.sql
13
14# Update HoneyAegis
15git pull
16docker compose pull
17docker compose up -d
18
19# Clear old attack data (careful!)
20docker exec honeyaegis-postgres psql -U honeyaegis -c \
21  "DELETE FROM sessions WHERE created_at < NOW() - INTERVAL '30 days';"

Common issues:

• Port conflicts: Another service using the honeypot ports. Check with netstat -tlnp
• NVIDIA driver mismatch: Container toolkit version must match driver. Reinstall toolkit after driver updates.
• Vector not shipping logs: Check docker compose logs vector. Usually a network/firewall issue between nodes.
• Ollama slow: Verify GPU access with docker exec honeyaegis-ollama nvidia-smi

What's Next

You now have a production honeypot network generating real threat intelligence. Here's how to evolve it:

• Let it run for a week. You'll be surprised how quickly attacks appear—usually within hours.
• Tune honeypot "stickiness." Configure Cowrie to emulate a more realistic filesystem, keeping attackers engaged longer.
• Add honey tokens. Deploy fake credentials that trigger instant alerts when used.
• Integrate threat feeds. Connect to MISP or AbuseIPDB for enriched attacker context.
• Expand your sensor fleet. Deploy additional Pi sensors at different network egress points.

Commercial platforms charge $5,000/year to show you what's attacking your network. You just built the same capability for the cost of a Pi and some electricity. The attackers are coming whether you watch them or not. Now you're watching.

Deployment Checklist

☐ Pi 5: Static IP assigned, Docker installed, sensor stack running

☐ Alienware: NVIDIA toolkit installed, Docker running, brain stack deployed

☐ Ollama: llama3.1:8b model pulled, GPU acceleration verified

☐ Network: Port forwarding configured (honeypot ports only!)

☐ Brain isolation: Verified brain has NO internet exposure

☐ Dashboard: Accessible at internal IP, admin password changed

☐ Vector: Logs flowing from sensor to brain

☐ First attack: Test by attacking your own honeypot

☐ AI analysis: Verify Ollama generates threat summaries

The Hacker's Path

This guide pairs with the security series.

Part 1: Introduction Part 2: Flipper Mastery HoneyAegis Guide ✓ Part 3: Kali Fundamentals Part 4: Exploitation