Mirage

Mirage is a self-hosted honeypot intelligence platform. It exposes a set of honeypots to the internet, ships everything attackers do into an ELK pipeline, enriches each attacker IP against threat intelligence sources, runs AI analysis on the activity, and shows the whole picture in a real-time web portal.

I built it to answer a simple question: who is actually knocking on an exposed server, and what are they trying to do? The result is a full pipeline that goes from raw packets to a readable threat story.

What it does

• Runs Cowrie (SSH/Telnet), Dionaea (malware capture), Honeyd (fake hosts), and a decoy VPN login page that records every credential and probe.
• Captures network traffic with Zeek and runs Suricata as an IDS on top.
• Normalizes every log format into one schema through Logstash and stores it in Elasticsearch.
• Scores each attacker IP using VirusTotal, AbuseIPDB, Shodan, OTX, GreyNoise, IPInfo, MalwareBazaar, and MetaDefender, and runs captured binaries through local YARA rules.
• Uses an LLM (Groq LLaMA 3.3, with Gemini as a fallback) to write per-IP threat narratives, group attacks into campaigns, generate Sigma rules, and post a daily digest.
• Serves a Vue portal with dashboards, a live attack map, session replay, PCAP downloads, malware analysis, campaign clustering, and a blocklist you can push to the host firewall.

Architecture

flowchart TD
    net["Attackers / Internet"] --> hp["Honeypots<br/>Cowrie, Dionaea, Honeyd, Decoy VPN"]
    net --> cap["Zeek + Suricata<br/>packet capture and IDS"]
    hp --> pipe["Filebeat to Logstash to Elasticsearch"]
    cap --> pipe
    pipe --> enr["Enrichment<br/>8 threat-intel APIs + YARA"]
    enr --> ai["AI Engine<br/>Groq / Gemini"]
    pipe --> portal["Portal<br/>FastAPI + Vue 3"]
    enr --> portal
    ai --> portal
    portal --> caddy["Caddy<br/>automatic HTTPS"]

Loading

Everything runs as Docker containers split across three isolated networks so the honeypots can never reach the data or management layers directly.

Requirements

• Ubuntu Server 22.04 or 24.04
• Docker Engine 26+ with the Compose plugin
• 4 vCPU and 8 GB RAM to try it out, 6 vCPU and 12 GB RAM for real use
• The honeypot ports free on the host: 21, 22, 23, 80, 443, 445, 3306, 5060

Since Cowrie takes port 22, move your real SSH to another port before you start.

Running it

1. Get the code and set up your environment file.

git clone https://github.com/odytr/mirage.git
cd mirage
cp .env.example .env

Open .env and set the passwords, JWT_SECRET, and FIREWALL_AGENT_TOKEN. You can generate secrets with openssl rand -hex 32. The threat-intel API keys are all optional, so you can leave them blank and add them later. For a local run, leave DOMAIN=localhost.

2. Prepare the honeypot volumes.

docker run --rm \
  -v mirage-cowrie-logs:/cowrie/var/log/cowrie \
  -v mirage-cowrie-ttylogs:/cowrie/var/lib/cowrie/ttylogs \
  -v mirage-cowrie-downloads:/cowrie/var/lib/cowrie/downloads \
  -v mirage-cowrie-ssh-keys:/cowrie/var/lib/cowrie \
  cowrie/cowrie:latest sh -c "chown -R 999:999 /cowrie/var"

docker run --rm \
  -v mirage_dionaea-binaries:/opt/dionaea/var/lib/dionaea \
  dinotools/dionaea:latest sh -c "cd /opt/dionaea && cp -van template/lib var/"

3. Start the honeypots and the ELK stack.

docker compose build honeyd
docker compose up -d

Elasticsearch needs a minute or two to come up. Everything else waits for it.

4. Apply the Elasticsearch templates.

docker exec mirage-elasticsearch bash /opt/setup/setup_kibana.sh

5. Start the intelligence layer and portal.

docker compose --profile intelligence up -d

That is it. Check the containers with docker compose ps and open the portal at http://localhost:8080. Log in with the admin username and password from your .env. Kibana is at http://localhost:5601.

Want data to look at right away? Run bash scripts/attack.sh to fire some realistic traffic at the honeypots and populate the portal.

For public HTTPS, set DOMAIN to a domain you own and point its DNS at the server. Caddy will request a certificate automatically.

Configuration

All settings live in .env. Copy .env.example, which documents every value and marks what is required versus optional. Never commit your real .env, it is already gitignored.

Common commands

make up                              # start the full stack
make logs SERVICE=cowrie             # tail one service
make rebuild SERVICE=portal-backend  # rebuild and restart one service
make monitoring                      # add Prometheus and Grafana
docker compose ps                    # container status
docker compose down                  # stop, keep data

Project layout

cowrie/         SSH and Telnet honeypot
dionaea/        malware capture honeypot
honeyd/         virtual host honeypot
decoy/          fake VPN login page
zeek/           network capture scripts
suricata/       IDS ruleset and config
elastic/        Elasticsearch, Logstash, Filebeat, Kibana configs
enrichment/     IP enrichment service and YARA rules
ai-engine/      LLM analysis, Sigma rules, daily reports
portal/         FastAPI backend and Vue 3 frontend
caddy/          HTTPS reverse proxy
firewall-agent/ host iptables sidecar
monitoring/     Prometheus and Grafana
scripts/        demo traffic and helper scripts