HONEYPIE - the honeypot project

A flexible, extensible honeypot framework written in Go. This project provides multiple honeypot services with standardized JSON logging and a real-time dashboard for easy analysis of malicious activity.

---

Features

• Multi-Service Honeypot:
  • SSH: Captures passwords, public keys, and client versions.
  • Telnet: Captures username/password and environment variables.
  • HTTP/HTTPS: Mimics a WordPress installation and other common web applications.
  • SMTP(S) / FTP(S) / RDP: Captures authentication attempts and connection metadata.
  • SIP: Captures SIP requests.
• Packet Logger: Captures TCP SYN, UDP, and ICMP packets using libpcap.
• Data & Analysis:
  • Real-time Dashboard: Built-in UI for visualizing logged events.
  • Prometheus Metrics: Export stats for Grafana/Prometheus.
  • GeoIP Integration: ASN and City-level geolocation for logged IP addresses.

---

Deployment Options

Choose the setup method that best fits your environment:

1. Docker

Ideal for quick deployment and isolated environments.

# 1. Prepare data directory
mkdir -p ./data
cp config.json ./data/config.json

# 2. Build and start
docker-compose up -d

# 3. View logs
docker-compose logs -f

Note: Uses --network host and CAP_NET_RAW for packet capture.

2. Vagrant

Ideal for testing in a clean, local virtual machine.

vagrant up
vagrant ssh
cd /vagrant
./honeypot -config config.json

The VM is pre-configured with Go 1.25.5 and all necessary C libraries.

3. Raspberry Pi

For dedicated hardware deployment. See the Raspberry Pi Setup Guide for details on hardening and firewall configuration.

4. Building from Source

For manual installation on Linux systems.

Prerequisites:

• Go 1.26.0+
• libpcap-dev, duckdb

# Debian/Ubuntu dependencies
sudo apt-get install libpcap-dev duckdb

# Build command
CGO_ENABLED=1 CGO_LDFLAGS="-lduckdb" go build -tags=duckdb_use_lib .

---

Configuration

The honeypot uses a JSON configuration file (default: config.json).

Example Configuration

{
  "listen_addr": "0.0.0.0",
  "interface": "eth0",
  "ui_port": 8081,
  "ssh_ports": [22, 2222],
  "http_ports": [80, 8080],
  "city_db_file": "/opt/data/GeoLite2-City.mmdb",
  "asn_db_file": "/opt/data/GeoLite2-ASN.mmdb",
  "city_db_url": "https://git.io/GeoLite2-City.mmdb",
  "asn_db_url": "https://git.io/GeoLite2-ASN.mmdb",
  "database_file": "/opt/data/honeypot.db"
}

Configuration Options

Field	Type	Default	Description
listen_addr	string	0.0.0.0	Bind address for all services.
log_file	string	""	Log file path.
database_file	string	""	Path to the DuckDB database file.
ui_port	uint	0	Dashboard port (0 to disable).
ui_password	string	""	Dashboard password.
api_token	string	""	API token for the metrics and blocklist API.
disable_metrics	bool	false	Disable metrics collection.
disable_hw_metrics	bool	false	Disable hardware metrics collection.
disable_dashboard	bool	false	Disable dashboard server.
interface	string	""	Network interface for raw packet capture.
bpf_expression	string	""	BPF expression for packet capture filtering.
ssh_ports	array	[]	Ports for the SSH honeypot.
telnet_ports	array	[]	Ports for the Telnet honeypot.
rdp_ports	array	[]	Ports for the RDP honeypot.
smtp_ports	array	[]	Ports for the SMTP honeypot.
smtps_ports	array	[]	Ports for the SMTPS honeypot.
ftp_ports	array	[]	Ports for the FTP honeypot.
ftps_ports	array	[]	Ports for the FTPS honeypot.
sip_ports	array	[]	Ports for the SIP honeypot.
http_ports	array	[]	Ports for the HTTP honeypot.
https_ports	array	[]	Ports for the HTTPS honeypot.
city_db_file	string	""	Path to MaxMind GeoIP2 City database.
asn_db_file	string	""	Path to MaxMind GeoIP2 ASN database.
city_db_url	string	""	URL to download City database if missing.
asn_db_url	string	""	URL to download ASN database if missing.
trusted_proxies	array	[]	IPs of trusted proxies (e.g., Nginx). If the request comes from a trusted proxy, headers like X-Real-Ip and X-Forwarded-For are used to determine the client IP.

If ui_password is set, the dashboard will be protected by a password. The API token is used secure the metrics and blocklist API. Use a bearer token in the Authorization header to authenticate requests to the blocklist and metrics endpoints, if api_token is set.

GeoLite2 Database Updates

Honeypot can automatically download and update its GeoLite2 databases:

• Automatic Download: If city_db_url and asn_db_url are configured and the database files are missing, they will be downloaded automatically on startup.
• Manual Update: If the URLs are configured, you can trigger a manual update and reload of the databases directly from the System Statistics view in the dashboard.

See the example configuration config.json for a complete example.

---

Monitoring & Logging

Prometheus Metrics

Metrics are available at http://<addr>:<ui_port>/metrics if ui_port is enabled.

• honeypot_auth_attempts_total: Counts by service type.
• honeypot_packets_total: Raw packet counts (TCP/UDP/ICMP).
• honeypot_top_usernames: Most common attack credentials.

JSON Logging

All events are logged to stdout or a file in a structured format:

{
  "time": "2024-01-01T12:00:00Z",
  "type": "ssh",
  "event": "auth_attempt",
  "remote_addr": "192.168.1.100",
  "username": "admin",
  "password": "password123"
}

---

Security & Permissions

• Isolation: Always use Docker, Vagrant, a dedicated VM or a separate machine.
• Privileged Ports: To bind to ports < 1024 without root, use:

  sudo setcap cap_net_raw,cap_net_admin,cap_net_bind_service=eip ./honeypot
  

• Reverse Proxy: If a valid TLS certificate is needed, it is recommended to use Nginx as a reverse proxy in front of the honeypot.