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.

How a Learning Project Became a Defensive Platform

I was three months into learning Kali Linux and I hit a wall.

TryHackMe is great. HackTheBox is great. I'm not knocking either one. But every box on those platforms is a puzzle somebody else designed, with a known solution at the end, and a flag that says "good job, you followed the breadcrumbs." I wasn't learning to think like a defender because I was never defending anything real.

I wanted to see actual attacks. Real credentials getting sprayed at real services. Actual malware payloads landing in actual traps. Not a flag hidden in a /root directory, but genuine hostile traffic from bots and humans who had no idea they were being watched.

So I did what any reasonable person would do. I Googled "how to build a honeypot" and immediately got mad at the prices.

The commercial honeypot market is absurd. Thinkst Canary wants $5,000/year for five devices. Other vendors charge per sensor, per month, and every single one of them routes your threat data through their cloud first. They see your attackers before you do. They build their threat intelligence database on your network's exposure, then sell that intelligence back to the industry.

I didn't have $5,000. I did have a Raspberry Pi 5 sitting in a drawer and an old Alienware laptop running Kali. So I started building.

What started as "I want something real to practice on" turned into a full platform. Dockerized honeypot sensors on the Pi, a FastAPI backend with PostgreSQL on the Alienware, and local AI analysis running on the laptop's GTX 1070. No cloud dependencies. No subscriptions. No vendor middleman.

I named it HoneyAegis. The name isn't random.

In Greek mythology, Athena's Aegis wasn't just a shield you crouched behind. It bore the head of Medusa and literally turned enemies to stone. Athena didn't sit behind a wall waiting to get hit. She carried her shield AND her spear into battle. She had a plan.

That's the philosophy behind HoneyAegis. This isn't passive defense. You're watching attackers in real time, recording their sessions, capturing their malware, and having an AI on your own hardware explain what they're doing in plain English. You're not hiding. You're studying your enemy while they think they're winning.

And here's the part that actually matters: we're building this for everyone. Not the $5,000/yr enterprise crowd. Not the "contact sales for pricing" gatekeepers. If you have a Pi and an afternoon, you can run the same threat intelligence operation that Fortune 500 companies pay six figures for.

HoneyAegis is 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 (and Why Should You Care)?

I know, I know. "Why would I voluntarily invite attackers onto my network?" Fair question. Here's why:

• Early warning system. Attackers hit your honeypot before your real systems. You see them coming while they're still poking at decoys.
• Free threat intelligence. Learn what tools they use, what credentials they try, what they're actually after. This information used to cost real money.
• Attack pattern database. Over time you build a library of techniques specific to your network's exposure. That's personalized intel no vendor can sell you.
• Hands-on training. Watch real attacks unfold in real time. Nothing simulated. Nothing scripted. Just actual hostile traffic doing actual hostile things.
• Safe pentest target. A controlled environment for your own offensive practice that logs everything you do, from both sides.

Here's something most people don't realize: the typical home network gets scanned thousands of times a day by automated bots. Most of that traffic bounces off closed ports and you never notice. A honeypot gives those bots something to find, then records everything they do after they find it. You turn background noise into actionable intelligence.

What HoneyAegis Runs

HoneyAegis bundles three proven open-source honeypot engines, each covering different attack surfaces:

Cowrie handles SSH and Telnet. Records full session transcripts, captures every credential attempt, logs every command an attacker types. When someone SSHs in with root/password123, you get the complete recording of what they did next.

Dionaea is the malware catcher. Emulates SMB, FTP, HTTP, and other services, then stores the actual malware payloads attackers try to drop. You can analyze what they're deploying against your network.

OpenCanary covers the rest. Windows shares, MySQL, SSH, and a dozen other services. It casts the broadest net of the three.

All three ship their logs to a central brain node running local AI analysis. The AI reads attack sessions and generates plain-English summaries of what happened. No security degree required to understand the output.

The Two-Node Architecture

This is where HoneyAegis stops being "a honeypot" and starts being "a platform." Most honeypot tutorials tell you to run everything on one box. That's fine for a weekend experiment. It's terrible for anything you actually want to rely on.

HoneyAegis uses a deliberate two-node split: the sensor faces the internet, the brain stays protected behind your network.

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 split them?

The sensor is intentionally exposed. It will be attacked. That's the entire point. And if something goes catastrophically wrong, if an attacker somehow escapes the honeypot containers, the Pi is a $60 device with nothing on it except decoys. Wipe the SD card. Redeploy. Thirty minutes and you're back online.

The brain holds 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. Even if the Pi gets completely owned, the brain is untouched.

This two-node design means you can treat the sensor as genuinely disposable. Enterprise honeypot vendors sell you dedicated hardware appliances for thousands of dollars, and if one gets compromised you're filing insurance claims. With HoneyAegis, your most exposed component is a $60 single-board computer running containers. The risk math changes completely when your front line is cheap enough to throw away.

Hardware: What We're Running

This isn't the only valid configuration. It's our optimal setup using hardware we already had. You probably have something similar collecting dust somewhere.

NODE 1: SENSOR (Raspberry Pi 5 4GB)

NODE 2: BRAIN (Alienware 15 R3)

Building the Sensor: Pi 5 Setup

Enough theory. Time to build this thing from bare metal. We start with the sensor, the Pi 5 that faces the internet and does the dangerous work.

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

Replace the IP addresses below 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

Building the Brain: Alienware Setup

Now the fun part. The brain is the protected node that processes everything the sensor catches. This is where the AI lives, where the database grows, and where you'll spend most of your time staring at dashboards instead of sleeping.

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, which is required for Ollama to do anything useful:

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 mess things up. I've seen it in GitHub issues, on Reddit, in Discord DMs. Someone deploys the whole stack, gets excited, and then port-forwards their PostgreSQL database to the internet. Please don't be that person.

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. From the outside, your Pi looks like a badly secured server. From the inside, it's a trap with a notebook.

The Dashboard: Where It Gets Addictive

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. Fair warning: this is weirdly addictive.
• GeoIP map: Visual representation of where attacks originate. Spoiler: everywhere.
• Session recordings: Full transcripts of SSH/Telnet sessions, exportable as MP4/GIF. Watch an attacker explore your fake filesystem in real time.
• AI summaries: Ollama-generated explanations of attack patterns in plain English. "This attacker attempted credential stuffing using a list of common IoT default passwords, then tried to download a cryptocurrency miner."
• Statistics: Attack frequency, common credentials, targeted services, trends over time.
• Alerts: Set up Slack, Discord, or email notifications via Apprise so you know the moment something interesting happens.

The first time you see a bot from Eastern Europe try "root/toor" on your honeypot and then attempt to download a crypto miner, you'll understand why this is better than any CTF box. That's not a puzzle someone designed. That's a real attacker doing real attacker things on your fake server, and your AI is calmly narrating the whole thing.

Attack Your Own Honeypot

Here's the part I was building toward from the beginning. Remember how I said I wanted something real to practice on? This is it.

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 own 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

Watching the AI describe your own attack in clinical detail is genuinely humbling. "The attacker connected via SSH using commonly targeted credentials, then executed system enumeration commands consistent with post-exploitation reconnaissance." Yeah, that was me. That was me with Hydra and rockyou.txt feeling like a big-time hacker, and the AI just calmly narrated it like a wildlife documentary.

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?

No. Absolutely not. I love Home Assistant. I wrote a separate guide on setting it up. But putting it on the same device as your internet-facing honeypot is like storing your house keys inside the mailbox.

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 door locks and thermostat.

Use a separate Pi for Home Assistant. They're sixty bucks. You'll survive.

The ~1.5 GB of headroom on the honeypot Pi isn't wasted, though. HoneyAegis has plans for it.

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:

• Conpot (~200 MB): Industrial control system honeypot. Emulates PLCs and SCADA systems. If someone is scanning for vulnerable infrastructure, you'll know.
• Mailoney (~100 MB): SMTP honeypot. Captures spam bots and credential harvesters targeting email servers.
• Elasticpot (~150 MB): Elasticsearch honeypot. Catches bots scanning for exposed clusters, which is disturbingly common.
• ADBHoney (~100 MB): Android Debug Bridge honeypot. Detects mobile-targeting attackers.
• Honey tokens: Fake AWS credentials and API keys that trigger alerts when used anywhere on the internet.

The architecture handles this cleanly. HoneyAegis uses a modular Docker Compose structure where 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.

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 and Maintenance

Real talk: this is a Docker stack on Linux. Most problems are Docker problems or network problems, not HoneyAegis problems.

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 your driver version. Reinstall the toolkit after driver updates.
• Vector not shipping logs: Check docker compose logs vector. Usually a network or firewall issue between nodes.
• Ollama running slow: Verify GPU access with docker exec honeyaegis-ollama nvidia-smi. If it's running on CPU instead of GPU, something went wrong with the NVIDIA container toolkit setup.

Go Build Your Shield (and Your Spear)

The attackers are coming whether you watch them or not. Automated scanners don't care if you're a Fortune 500 company or someone's home lab running off a Pi in the closet. They scan everything, all the time, from everywhere.

The only variable is whether you're paying attention. Now you are. And you're paying about sixty bucks for the privilege instead of five grand.

This isn't sitting around waiting to get hit. This is Athena with her shield AND her spear. Your honeypot is the shield that catches attacks. Your AI is the spear that turns raw data into intelligence. And the whole thing runs on your hardware, on your network, under your control.

No vendor sees your data first. No cloud processes your attacks before you do. No subscription fee gates your own threat intelligence behind a paywall.

"The best defense is a good offense." That quote gets attributed to everyone from Sun Tzu to Mike Tyson. Whoever said it first was probably talking about honeypots. Probably.

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