# _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.

> [!WARNING]
>
> **Never run honeypots on production systems** without proper isolation. Honeypots are designed to attract and interact with potentially malicious traffic.
>
> The dashboard was created with heavy use of AI tools. **Do not make it available to the internet. It is only for local use.**
>
> **USE AT YOUR OWN RISK!**

---

## 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.

```bash
# 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.

```bash
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](RaspberryPi_Setup.md) 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`

```bash
# 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

```json
{
  "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](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:

```json
{
  "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:
  ```bash
  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.
