# HoneyMesh Operator Manual (Extended) Date: 2026-03-22 Version: v2.2.3-Golden-Nectar This manual is written for operators deploying HoneyMesh in lab, production, or distributed environments. It covers installation, configuration, UI workflows, licensing, Trusted Network Sharing, JA4-first TLS fingerprinting, and operational procedures. --- **1. Overview** HoneyMesh is a distributed cyber defense platform that combines high-interaction traps, kernel-level enforcement, JA4-first TLS fingerprinting, and trust-scored intelligence sharing across a secure mesh. Core goals: - Detect and capture adversary activity on exposed services. - Enforce bans at kernel speed via eBPF/XDP. - Share trusted, sanitized attack intelligence between opted-in Pro nodes. - Provide a unified operator console for control and visibility. --- **2. Requirements** Runtime requirements: - Linux kernel 5.4+ (eBPF/XDP). - Go 1.21+ to build from source. - Root privileges to attach XDP and manage BPF maps. Package layout (when installed as a `.deb`): - Binary: `/usr/bin/honeymesh` - Config: `/etc/honeymesh/honeymesh.json` - Data: `/var/lib/honeymesh/` - Static UI assets: `/usr/share/honeymesh/web/` - eBPF source archive: `/usr/share/honeymesh/ebpf-src.tar.gz` --- **3. Install And Run** Source build: ```bash cd /home/r2d2/Desktop/HM3/HM3 go build -o honeymesh . ``` Run from source: ```bash sudo ./honeymesh -config /etc/honeymesh/honeymesh.json ``` Package install: ```bash sudo dpkg -i /path/to/honeymesh_2.1.2-HiveQueen_amd64.deb ``` Run package: ```bash sudo /usr/bin/honeymesh -config /etc/honeymesh/honeymesh.json ``` Startup banner: ``` 🍯 Honey Mesh v2.2.3-Golden-Nectar Active ``` --- **4. Admin Token** The dashboard and API require an admin token. Behavior: - If `admin_token` is empty, a random token is generated at startup. - The token is printed to the console. --- **5. Licensing** License tiers: - `COMMUNITY`: Local-only protection, local dashboard, local analytics, no trusted network participation. - `PRO`: Includes all Community capabilities plus premium controls and optional Trusted Network Sharing. Trusted Network Sharing: - Available only in `PRO`. - Disabled by default. - Requires explicit operator opt-in. - When off, HoneyMesh will not publish or receive community attack intelligence. - When a Pro license expires or becomes invalid, premium features and Trusted Network Sharing are disabled immediately. - Mesh participation also requires a valid signed Pro capability at join, heartbeat, and event-ingest time. - Shared intelligence events are signed per event and rejected if stale, replayed, or rate-limited. - HoneyMesh federation is `v2` only. Unsigned, unversioned, or non-`v2` mesh payloads are rejected. Upload license: - Click the license pill in the header. - Upload `license.json`. - The license is validated immediately and the UI updates. --- **6. Configuration (`honeymesh.json`)** Key controls: - `bind_ip`: Dashboard and API bind address. - `web_port`: Dashboard HTTPS port. - `license_tier`: Persisted effective tier state (`free` or `pro`). - `trusted_network_sharing_enabled`: Persisted Trusted Network Sharing opt-in state. - `security.whitelist`: CIDRs always allowed. - `security.trusted_peers`: Mesh peers treated as trusted. - `security.ja4_blacklist`: JA4 fingerprints to block aggressively. - `security.ja4_labels`: Optional JA4 labels for operator readability. - `security.ja3_blacklist`: Legacy JA3 blacklist support during migration. - `security.ja3_labels`: Legacy JA3 labels during migration. - `security.mesh_event_rate_limit_per_min`: Per-publisher inbound intelligence cap. - `security.mesh_event_burst`: Short-window burst cap for shared intelligence. - `security.mesh_replay_window_s`: Allowed clock skew / replay window for shared events. - `security.mesh_data_classification`: Default shared-data level (`L1` to `L4`). - `security.trap_ban_hits`: Scan threshold. - `security.trap_ban_window_s`: Scan window. --- **7. Dashboard Layout** The dashboard is a single-page operator console. Header: - Logo and Cluster ID. - License status pill (click to upload `license.json`). - Mode controls: `TEST MODE`, `ENFORCE`, `LOCKDOWN`. License and sharing status: - Header and peer panel show `License: Community` or `License: Pro`. - Peer panel shows `Trusted Network Sharing: Off` or `Trusted Network Sharing: Enabled`. - Free users see upgrade messaging for HoneyMesh Defense Network features. KPIs: - `PROTECTION SURFACE (LOCAL / NETWORK)` - `DEFENSE NETWORK (NODES / INTERFACES ONLINE)` - `BLOCKS (LOCAL / NETWORK)` - `THREATS (LOCAL / NETWORK)` Main grid panels: - `TRAPS` - `INTERFACES` - `HONEYMESH DEFENSE NETWORK` Live panel: - `LIVE THREAT STREAM` (click to open modal) - `DOWNLOAD CSV` --- **8. Traps Panel** Purpose: Configure honeypot trap listeners and scan thresholds. Header controls: - `SCAN` settings: - `PORTS`: trap hit count threshold - `SEC`: time window in seconds - `SAVE` Trap row actions: - `ENABLE / DISABLE`: Start or stop a trap port. - `WATCHDOG`: Trigger immediate ban on any hit (disabled when trap is enabled). - `EDIT`: Edit banner text for that port. Trap indicators: - Status shown as `LISTENING`, `WATCHDOG`, or `DISABLED`. - Colored status for fast scan. --- **9. Interfaces Panel** Purpose: Attach or detach local XDP protection from network interfaces. Per-interface actions: - `ATTACH`: Enable enforcement on interface. - `DETACH`: Disable enforcement on interface. Status fields: - IPs assigned. - Link state `up` or `down`. - Mode `off`, `xdp`, or `unknown`. --- **10. HoneyMesh Defense Network Panel** Purpose: Manage trusted peers, mesh participation, and shared defense status. Header actions: - `TRUST LEVELS`: Open trust modal with peer scoring controls. - `TRUSTED PEERS`: Open trusted peers and allowlist editor. - `JOIN`: Add a new peer to the mesh. Status area: - HoneyMesh Defense Network participation status. - Trusted Network Sharing state. - Federation validation state and counters are exposed through `/api/health`. - Upgrade messaging when the node is in Community mode. --- **11. Live Threat Stream Panel** Purpose: Real-time events and active bans. Events table columns: - `TIME` - `IP ADDRESS` - `PORT` - `JA4 / JA3 LEGACY` - `APP` - `SESSION` - `ACTION` Fingerprint behavior: - JA4 is the primary TLS fingerprint shown in the UI. - JA3 is shown only as legacy compatibility context when present. - Remote mesh intelligence events can also carry JA4 and legacy JA3 context. - Remote mesh intelligence is accepted only after capability, signature, replay, and rate checks pass. Event actions: - `BLOCK`: Manual ban of an attacker IP. Active bans table columns: - `IP` - `EXPIRES` (shows `PERMANENT` for long‑lived bans) - `JA4 / JA3 LEGACY` - `ACTION` Ban actions: - `ALLOW`: Remove ban and allow traffic. - `WHITELIST`: Add to allowlist. - `RELEASE`: Remove ban. - `EXTEND`: Extend ban duration. - `PERMANENT`: Apply permanent ban. Controls: - `DURATION (HRS)`: Input for `EXTEND` action. - `ALLOW IP`: Force allow an IP. Safety confirmations: - `PERMANENT` requires confirmation. - `RELEASE` requires confirmation. --- **12. Live Modal** Click `LIVE THREAT STREAM` to open a full-screen modal. Tabs: - `EVENTS` - `BANS` Features: - Shows larger tables with the same action buttons. - `DURATION (HRS)` remains available on BANS tab. --- **13. Trust Levels Modal** Purpose: Control peer trust level and penalties. Columns: - `PEER` - `SCORE` - `LEVEL` - `REPORTS` - `VALID` - `INVALID` - `LAST` - `ACTION` Actions: - `L0` `L1` `L2` `L3`: Set trust level. - `PENALIZE`: Penalize a peer. - `REFRESH` --- **14. Trusted Peers Modal** Purpose: Central allowlist, trusted peer editor, and Trusted Network Sharing controls. Elements: - `Enable Trusted Network Sharing` toggle - `BASE ALLOWLIST` checkbox. - Whitelist editor (CIDR or IP, one per line). - Trusted peers editor. - `REFRESH` - `SAVE` Notes: - IPs are normalized to `/32` or `/128` automatically. - Base allowlist includes RFC1918, localhost, and link-local. - Trusted Network Sharing remains unavailable in Community mode. - In Pro mode, Trusted Network Sharing is still off until explicitly enabled. - HoneyMesh uses a stable node identity stored in `identity.key` to sign shared intelligence events. - The default federation sharing level is `L2`: attacker IP, JA4, JA3 legacy, protocol/category metadata, and no raw payload evidence. --- **15. API Endpoints (Operator Reference)** Common endpoints: - `GET /api/events` - `GET /api/bans` - `GET /api/bans/meta` - `GET /api/license-info` - `GET /api/security` - `POST /api/ban` `{ip, reason}` - `POST /api/ban/extend` `{ip, ttl_seconds}` or `{ip, permanent: true}` - `POST /api/ban/release` `{ip}` - `POST /api/allow` `{ip}` - `POST /api/mode` `{mode}` - `POST /api/trap` `{port, enabled|watchdog|banner}` - `GET /api/ifaces` - `POST /api/iface` `{iface, attach}` - `GET /api/peers` - `POST /api/mesh/join` `{peer}` - `POST /api/mesh/revoke` `{peer}` - `POST /api/license` (upload license JSON) - `POST /api/security` for scan thresholds, allowlist settings, trusted peers, and Trusted Network Sharing state Headers: - `X-Honey-Token`: Admin token. --- **16. Troubleshooting** Startup errors: - `failed to raise memlock limit`: must run as root or set memlock limits. - `license invalid` or `license expired`: HoneyMesh falls back to Community mode and disables Trusted Network Sharing. Mesh broadcast timeouts: - Check peer reachability `ping`. - Check port open `nc -vz peer 9000`. - Check peer service status and mesh config. - Verify the node is in Pro mode and Trusted Network Sharing is enabled. UI not updating: - Verify admin token. - Check console logs for websocket errors. --- **17. Operational Notes** Ban lifecycle: - Bans are stored in memory and persisted in SQLite. - Expired bans are cleaned up automatically. - Permanent bans use a far‑future expiry and display `PERMANENT` in UI. Security posture: - XDP enforcement blocks before the OS TCP/IP stack. - Mesh intelligence is gated by trust levels. - Trusted Network Sharing is disabled unless Pro and explicitly enabled. - TLS fingerprinting is JA4-first with JA3 retained as legacy fallback during migration. --- **18. Quick Reference** Common operator actions: - `TEST MODE`: detect only, no enforcement. - `ENFORCE`: active blocking allowed. - `LOCKDOWN`: aggressive enforcement. - `Enable Trusted Network Sharing`: opt in to HoneyMesh Defense Network participation. - `BLOCK`: manual ban from events. - `PERMANENT`: lock an IP indefinitely. - `RELEASE`: remove a ban.