HoneyWire Sentinel is a lightweight, distributed deception hub and Micro-SIEM. It is designed to deploy silent, asynchronous sensors that act as traps or lures across multiple servers, detect unauthorized access, trap automated botnets, and report telemetry back to a centralized dashboard in real-time.

There are existing lightweight SIEM/Deception Hubs, but few feature a clean looking, easy to use dashboard with instant webhooks without being incredibly resource-intensive. This project aims to fill that gap in the cybersecurity tool landscape for homelabs and SMBs.

Screenshots

Main Dashboard

Payload Inspector

🔌 The Universal Event Standard (Bring Your Own Sensor)

Community Sensors

The true power of HoneyWire is that the Hub is completely sensor-agnostic. You are not limited to the included official sensors.

By adhering to the HoneyWire Event Standard V1.0, you can write a script in any language (Bash, Go, Rust, Python) to monitor anything, and the Sentinel UI will dynamically parse, syntax-highlight, and render your forensic data.

Whether it is a Deep Packet Inspection (DPI) engine, a DNS sinkhole, a Canary Token embedded in a PDF, an Email Honeypot, or a simple TCP Port Tripwire, just POST this JSON to the Hub:

{
  "contract_version": "1.0",
  "sensor_id": "core-dpi-engine",
  "sensor_type": "deep_packet_inspection",
  "event_type": "malformed_jwt_detected",
  "severity": "critical",
  "timestamp": "2026-04-03T11:30:00Z",
  "action_taken": "ip_banned",
  "details": {
    "source_ip": "104.28.19.12",
    "target": "Auth Gateway",
    "protocol": "TCP",
    "headers_stripped": true,
    "payload_sample": [
      "Authorization: Bearer eyJhbG... [TRUNCATED]",
      "User-Agent: curl/7.64.1"
    ]
  }
}

Note: If you build your sensor using the official HoneyWire Go SDK, this JSON formatting and delivery is handled for you automatically.

The Hub's frontend automatically translates arrays into syntax-highlighted code blocks and primitive values into clean detail tags.

Features

The Sentinel UI: A fully responsive dashboard featuring Dark/Light mode, real-time Chart.js threat distribution, and dynamic forensic payload inspection.
Suite of Official Sensors: Includes a native Go TCP Tarpit, Web Router Decoy, File Canary (FIM), ICMP Canary, and Network Scan Detector.

Architecture

HoneyWire is split into three independent microservices:

/Hub: The central brain. A pure Go binary running an embedded SQLite database and the web dashboard. It runs as a non-root user inside a Distroless container, safely mounting data to a dedicated volume.
/Sensors: The decoy nodes. Statically-linked Go binaries that listen on vulnerable ports, trap attackers, and securely POST intrusion data back to the Hub.
/SDKs: Official libraries (like sdk-go) that handle secure Hub communication so community developers can easily build new sensors.

🚀 Quick Start Guide

Deploying HoneyWire takes less than 60 seconds using our pre-built GitHub Container images. No compiling is required.

Create a new directory on your server, and create two files: docker-compose.yml and .env.

1. The `docker-compose.yml`

version: '3.8'

services:
  # 1. THE PERMISSION FIXER: Runs once to ensure the Hub can write to the data volume
  permission-fixer:
    image: alpine:latest
    command: sh -c "chown -R 65532:65532 /data"
    volumes:
      - ./honeywire_data:/data

  # 2. THE HUB: The central Go-based dashboard and API
  hub:
    image: ghcr.io/andreicscs/honeywire-hub:latest
    container_name: honeywire-hub
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./honeywire_data:/data
    depends_on:
      permission-fixer:
        condition: service_completed_successfully
    user: "65532:65532"
    cap_drop:
      - ALL
    env_file: 
      - .env

  # 3. EXAMPLE SENSOR: The TCP Tarpit (See /Sensors for more)
  tcp-tarpit:
    image: ghcr.io/andreicscs/honeywire-tcptarpit:latest
    container_name: hw-tcp-tarpit
    restart: unless-stopped
    network_mode: "host" # Required to capture true source IPs
    cap_drop:
      - ALL
    env_file: 
      - .env

volumes:
  honeywire_data:

2. The `.env` Configuration

# ==========================================
# HUB CONFIGURATION
# ==========================================
# Secret key used by sensors to authenticate with the Hub
HW_HUB_KEY=change_this_to_a_secure_random_string

# Optional: Protect the Web UI (Leave blank for no password)
HW_DASHBOARD_PASSWORD=admin

# Optional: Push Notifications
HW_NTFY_URL=https://ntfy.sh/your_private_topic
# HW_GOTIFY_URL=https://gotify.example.com/message
# HW_GOTIFY_TOKEN=your_token

# ==========================================
# SENSOR EXAMPLE: TCP TARPIT
# ==========================================
# Point this to your Hub's IP and Port
HW_HUB_ENDPOINT=http://127.0.0.1:8080
HW_SENSOR_ID=tarpit-01

# Ports to monitor, behavior mode, and fake service banner
HW_DECOY_PORTS=22,2222,3306
HW_TARPIT_MODE=hold
HW_SEVERITY=high
HW_TARPIT_BANNER=SSH-2.0-OpenSSH_8.2p1 Ubuntu-4ubuntu0.1\r\n

3. Start the Trap

Run the following command to pull the images and start the honeypot:

docker compose up -d

Access the dashboard at http://localhost:8080 (or your server's IP).

🧪 Testing the Trap

Once your containers are up, the Tarpit sensor should appear as ONLINE in the Fleet Health section of the dashboard within 30 seconds.

To verify the detection loop, use netcat from a different machine (or a different terminal) to trigger the decoy:

# Connect to your decoy port (e.g., 2222)
nc <your-server-ip> 2222

Observe the Lure: If HW_TARPIT_MODE is set to hold or echo, you will see your fake service banner immediately.
Interact: Type a string (e.g., admin or exploit_payload) and press Enter.
Close: Press Ctrl+C to terminate the test connection.
Verify Capture: - The connection will be intentionally stalled (Tarpit).
- Check the HoneyWire Dashboard; the event, your Source IP, and the payload will appear instantly.
- If configured, you will receive a push notification on your mobile device.

Security Notes

API Secret: Ensure your HW_HUB_KEY is strong and identical on both the Hub and the Sensors. The Hub will reject any payloads with mismatched keys.
System Arming: You can toggle the "System Armed" button in the Hub UI to temporarily disable push notifications while doing internal network maintenance or vulnerability scanning.
Container Hardening: HoneyWire utilizes gcr.io/distroless/static-debian12:nonroot. Do not attempt to use docker exec -it <container> sh as there is no shell binary or package manager included in the images by design.
Distributed Deployment: It is highly recommended to run the Hub and its Sensors on separate physical or virtual machines. If an attacker compromises a sensor node, they should not have immediate local access to the centralized Hub.
Encryption (HTTPS): Always serve the Hub Web GUI and API over HTTPS using a reverse proxy (like Nginx, Caddy, or Traefik). Failure to do so exposes your HW_HUB_KEY and HW_DASHBOARD_PASSWORD to network sniffing.

Tech Stack

Backend: Go 1.25, net/http (Standard Library), SQLite (Pure Go Driver)
Frontend: HTML5, TailwindCSS, Alpine.js, Chart.js
Infrastructure: Docker, Docker Compose, Distroless Linux Sandbox

Versioning and API Reference

HoneyWire uses a single source of truth version file: VERSION in the repo root.
The runtime version is exposed via an env override: HW_VERSION (Hub + Sensors), which defaults to VERSION.
Hub endpoint:
- GET /api/v1/version → returns { "version": "1.0.0" }
API docs file: 📖 API.md with full backend route reference and sample payloads.

Key API Endpoints

GET /api/v1/system/state / PATCH /api/v1/system/state
GET /api/v1/sensors
GET /api/v1/events
PATCH /api/v1/events/read, PATCH /api/v1/events/{event_id}/read, DELETE /api/v1/events
POST /api/v1/heartbeat (Sensor heartbeat)
POST /api/v1/event (Sensor event reports)

Operational Checklist

Set HW_HUB_KEY for all components.
Set optional HW_DASHBOARD_PASSWORD.
Rebuild/redeploy containers after any version bump in VERSION or environment variable changes.

Languages

Go 50.4%

Vue 34.9%

TypeScript 8.7%

Python 2.4%

CSS 1.8%

Other 1.8%

README.md

📋 Table of Contents

HoneyWire