Beelzebub Honeypot on AWS User Guide

Overview

This image runs Beelzebub, the open source low code honeypot and deception framework. Beelzebub stands up decoy services that look like real infrastructure, a fake SSH shell, a fake web server and a fake database, so that any connection to them is, by definition, suspicious. Every interaction is captured as a structured event and exposed as Prometheus metrics, giving you an early warning tripwire for reconnaissance and intrusion attempts inside your network. The image is delivered as a ready to use appliance: beelzebub.service and nginx.service are enabled and start on boot, so the moment you connect over SSH the deception layer is already listening.

This is a headless service. There is no web interface. The decoy services listen on port 2222 (SSH), 8080 (HTTP) and 3306 (a fake database). These decoy ports are deliberately separate from the real administrative sshd on port 22, so deploying the honeypot never interferes with how you manage the instance. Because a honeypot should only ever be exposed on purpose, the shipped security group opens ports 22 and 80 only, and the decoy ports stay closed until you deliberately open them.

The Prometheus metrics endpoint is the real management surface. Beelzebub binds it to the loopback interface, and nginx fronts it on port 80: an unauthenticated /health endpoint is available for load balancer probes, while /metrics requires a password. There are no shared or default credentials. A unique metrics password is generated on each instance's first boot and written to a root only file, and the decoy services use static built in responses so no external API key is needed.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Beelzebub. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes a short time after the instance state becomes Running and the status checks pass: the image resolves the instance address, generates a unique metrics password, writes the per instance welcome notes, and starts the services.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Beelzebub Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --metadata-options "HttpTokens=required" \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=beelzebub}]'

When the instance state is Running and both status checks pass, note its public or private IP address for the SSH step.

Step 3: Connect over SSH

Connect to the instance on the real administrative port 22 with your key pair. This is your normal, untouched admin access; it is not the honeypot. The login user depends on the operating system variant you launched.

Connecting to your instance

ssh -i /path/to/<key-name>.pem ubuntu@<public-ip>

Step 4: Read the Per-Instance Welcome Notes

On first boot the image generates a unique metrics password and writes a root only notes file recording it alongside this instance's endpoints and decoy ports. Keep this file secret.

sudo cat /root/beelzebub-info.txt

You will see your unique metrics password, the health and metrics URLs, and the decoy endpoints. The password shown here is unique to your instance:

METRICS_USER=cloudimg
METRICS_PASSWORD=<your-metrics-password>
METRICS_URL=http://<public-ip>/metrics
HEALTH_URL=http://<public-ip>/health
SSH_DECOY=<public-ip>:2222
HTTP_DECOY=http://<public-ip>:8080/
MYSQL_DECOY=<public-ip>:3306

Step 5: Confirm the Services Are Running

Check that both the honeypot daemon and the reverse proxy are active:

systemctl is-active beelzebub nginx

Both commands return active. For the full unit detail, including the non root process running the honeypot and the decoy ports it is listening on:

systemctl status beelzebub.service --no-pager

Step 6: The Secured Metrics Endpoint

The Prometheus metrics endpoint is the real management surface. The unauthenticated health probe is meant for load balancers and returns a simple ok:

curl -s http://127.0.0.1/health

The metrics endpoint itself requires the per instance password. Without it, nginx returns 401:

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1/metrics

With the password from your welcome notes it returns the live Prometheus counters. The following scrape writes the metrics to a file, then shows the honeypot event counters:

curl -s -u cloudimg:<your-metrics-password> http://127.0.0.1/metrics -o /tmp/metrics.txt
grep -E 'beelzebub_events_total|beelzebub_http_events_total' /tmp/metrics.txt

Point your own Prometheus at http://<public-ip>/metrics with the username cloudimg and this password to scrape honeypot activity into your dashboards and alerting.

Step 7: The Decoy Services and the Two Separate Surfaces

The whole point of this image is that the decoy services and your real administrative SSH are separate listeners. Confirm the real sshd on 22, the nginx metrics proxy on 80, and the three decoys on 2222, 8080 and 3306 are all bound:

ss -tlnH | awk '{print $4}' | grep -E ':(22|80|2112|2222|3306|8080)$' | sort

The decoy SSH deliberately presents a fake server identity so it looks like a different machine to an attacker, entirely separate from the real admin sshd on port 22. You can read the decoy banner directly:

timeout 8 bash -c 'exec 3<>/dev/tcp/127.0.0.1/2222; head -c 40 <&3'; echo

Step 8: Watch an Interaction Being Captured

Every connection to a decoy is written to the event log as a structured event. Send a probe to the HTTP decoy, then read the captured event out of the log:

curl -s -o /dev/null "http://127.0.0.1:8080/example-attacker-probe"
sleep 1
sudo tail -n 20 /var/lib/beelzebub/logs/beelzebub.log

The captured event records the protocol, HTTP method, the request path the attacker touched, the user agent, and the source address. Because nothing legitimate should ever touch a decoy, every such event is worth investigating.

Step 9: Open the Decoy Ports to Start Attracting Activity

The shipped security group opens ports 22 and 80 only, so out of the box nothing external can reach the decoys. To begin luring and logging activity, open the decoy ports in the instance security group to the networks you want to observe. Only ever expose a honeypot deliberately and to networks you understand. Replace <security-group-id> with your instance's security group and <your-mgmt-cidr> with the range you want to watch.

aws ec2 authorize-security-group-ingress \
  --group-id <security-group-id> \
  --ip-permissions \
    IpProtocol=tcp,FromPort=2222,ToPort=2222,IpRanges='[{CidrIp=<your-mgmt-cidr>}]' \
    IpProtocol=tcp,FromPort=8080,ToPort=8080,IpRanges='[{CidrIp=<your-mgmt-cidr>}]' \
    IpProtocol=tcp,FromPort=3306,ToPort=3306,IpRanges='[{CidrIp=<your-mgmt-cidr>}]'

Step 10: Add Your Own Decoy Service

The decoy services are defined by simple YAML files in /etc/beelzebub/services/. Copy one of the shipped definitions, edit its port, protocol and responses to model whatever service you want to imitate, and restart the daemon. Because this modifies the running honeypot, run it only when you are ready.

sudo cp /etc/beelzebub/services/http-8080.yaml /etc/beelzebub/services/http-9000.yaml
sudo nano /etc/beelzebub/services/http-9000.yaml   # set a new address and responses
sudo systemctl restart beelzebub.service           # apply the changes

Step 11: Optionally Enable the AI Backed Shell

Beelzebub can back its SSH decoy with a large language model so the fake shell answers arbitrary commands convincingly. This is disabled by default and needs no API key out of the box. To enable it, supply your own LLM API key in the core config and restart the service. Your key is your own per instance secret; it is never baked into the image.

sudo nano /etc/beelzebub/beelzebub.yaml   # add your own LLM plugin settings and API key
sudo systemctl restart beelzebub.service

Security Recommendations

• Deploy the honeypot on an isolated or closely monitored network segment. By design it invites malicious traffic, and its decoy services are intentionally fake.
• Keep the real administrative SSH on port 22 restricted to your management network, and open the decoy ports only to the ranges you intend to observe.
• Treat the metrics password in /root/beelzebub-info.txt as a secret and put the metrics endpoint behind TLS before exposing it beyond the instance.
• Ship the captured events to a SIEM or analytics pipeline so alerts fire the moment a decoy is touched.

Support

This image is published by cloudimg with 24/7 technical support by email and chat. We can help with decoy service configuration, the metrics endpoint and TLS, wiring the metrics into your monitoring, opening and placing the decoy ports safely, enabling the optional AI backed shell with your own key, backups, and upgrade planning.

Beelzebub is distributed under the GNU General Public License v3.0. cloudimg is not affiliated with or endorsed by the Beelzebub project or its authors. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.