# HoneyMesh Operator Manual Date: 2026-04-07 Version: v2.3.1-Iron-Hive This manual covers the current HoneyMesh operator workflow for local protection, Pro licensing, HoneyMesh Exchange connectivity, trusted mesh discovery, per-network trust, temporary join tokens, and day-to-day administration. --- **1. Overview** HoneyMesh is a distributed defense platform built around three layers: - Local traps and analytics to observe hostile activity. - Kernel-speed enforcement through eBPF/XDP. - Optional Pro-only shared defense through HoneyMesh Exchange and trusted mesh participation. HoneyMesh Exchange is a lightweight discovery and intelligence plane. It helps operators discover other HoneyMesh cluster IDs and receive shared attack intelligence when they explicitly opt in. Direct trust and peer federation still stay under operator control. Trusted mesh participation is the peer-to-peer layer. It is how approved HoneyMesh networks exchange validated defense signals after an operator chooses which external networks to trust and at what level. --- **2. Requirements** Runtime requirements: - Linux kernel 5.4 or newer. - Root privileges to attach XDP programs and manage BPF maps. - HTTPS certificates for the dashboard/API if you run outside a lab. - Go 1.21 or newer if building from source. Installed package layout: - Binary: `/usr/bin/honeymesh` - Primary config: `/etc/honeymesh/honeymesh.json` - Local data/state: `/var/lib/honeymesh/` - Dashboard assets: `/usr/share/honeymesh/web/` - eBPF source archive: `/usr/share/honeymesh/ebpf-src.tar.gz` Common local files used at runtime: - License file: `license.json` - Cluster identity: `cluster.id` - Mesh signing identity: `identity.key` --- **3. Install And Run** Build from source: ```bash cd /home/r2d2/Desktop/HM3/HM3 go build -o honeymesh . ``` Run from source: ```bash sudo ./honeymesh -config /etc/honeymesh/honeymesh.json ``` Install the current Debian package: ```bash sudo dpkg -i /path/to/honeymesh_2.3.1-Iron-Hive_amd64.deb ``` Run the packaged binary: ```bash sudo /usr/bin/honeymesh -config /etc/honeymesh/honeymesh.json ``` Startup banner: ```text 🍯 Honey Mesh v2.3.1-Iron-Hive Active ``` Generate a temporary trusted mesh invite token: ```bash ./honeymesh -config honeymesh.json -token ``` Join another HoneyMesh network with a temporary token: ```bash ./honeymesh -config honeymesh.json -join https://:9000/mesh/join -t ``` Manual exchange enrollment flow: ```bash ./honeymesh -config honeymesh.json -register-exchange https:// -enroll-token ``` Current recommended operator flow: - Upload a valid Pro `license.json` in the app. - Open `TRUSTED PEERS`. - Enable `Trusted Sharing`. - HoneyMesh bootstraps against the live exchange and stores its exchange credentials automatically. Uninstall: ```bash sudo systemctl stop honeymesh || true sudo systemctl disable honeymesh || true sudo dpkg -r honeymesh ``` Full uninstall including config and local state: ```bash sudo systemctl stop honeymesh || true sudo systemctl disable honeymesh || true sudo dpkg -P honeymesh sudo rm -rf /etc/honeymesh /var/lib/honeymesh /usr/share/honeymesh ``` --- **4. Admin Token** The dashboard and operator API require an admin token. Behavior: - If `admin_token` is empty, HoneyMesh generates one at startup. - The token is printed to the console. - API requests use the `X-Honey-Token` header. --- **5. Licensing And Feature Gates** License tiers: - `COMMUNITY`: Local-only protection, local dashboard, local analytics, no Exchange participation, no trusted mesh participation. - `PRO`: Community features plus premium dashboard controls, HoneyMesh Exchange opt-in, trusted mesh participation, and shared defense features. Important behavior: - Pro sharing features are off by default. - Operators must explicitly enable them. - If the Pro license is invalid or expired, HoneyMesh disables Exchange and trusted mesh participation immediately. - HoneyMesh validates the signed license locally before enabling Pro-only capabilities. Current shared-defense model: - `Trusted Sharing` is the in-app toggle that enables HoneyMesh Exchange integration. - HoneyMesh Exchange is used to discover cluster IDs and receive curated/shared attack intelligence. - `Trusted Mesh Networks` is a separate control for direct peer federation. - Exchange discovery does not automatically trust another network. - Operators choose trust network by network. --- **6. Configuration (`honeymesh.json`)** Top-level controls: - `node_name`: Friendly node name shown in the UI and exchange registration. - `bind_ip`: Dashboard and API bind address. - `web_port`: Dashboard HTTPS port. - `mesh_port`: Peer mesh port. - `admin_token`: Dashboard/API admin token. - `license_tier`: Persisted effective tier state. - `trusted_network_sharing_enabled`: Persisted Exchange opt-in state. - `trusted_mesh_network_enabled`: Persisted trusted mesh participation state. Mesh controls: - `mesh.peers`: Known direct peers. - `mesh.quorum`: Quorum ratio for mesh decisions. - `mesh.min_peers`: Minimum expected peer count. - `mesh.authoritative_peers`: Peer list treated as highly trusted. - `mesh.trusted_networks`: Cluster-level trust policy list. `mesh.trusted_networks` entries: ```json { "cluster_id": "cid_example", "trust_level": 2 } ``` Exchange controls: - `exchange.enabled` - `exchange.base_url` - `exchange.node_id` - `exchange.tenant_id` - `exchange.shared_secret` - `exchange.trusted_clusters` - `exchange.pull_interval_s` - `exchange.push_local_bans` - `exchange.pull_shared_feed` - `exchange.trust_threshold` - `exchange.feed_cursor` - `exchange.last_registered_at` Security controls: - `security.allowlist_base` - `security.whitelist` - `security.trusted_peers` - `security.ja4_blacklist` - `security.ja4_labels` - `security.ja3_blacklist` - `security.ja3_labels` - `security.mesh_event_rate_limit_per_min` - `security.mesh_event_burst` - `security.mesh_replay_window_s` - `security.mesh_data_classification` - `security.scan_ports` - `security.scan_window_s` - `security.trap_ban_hits` - `security.trap_ban_window_s` Notes: - `exchange.trusted_clusters` controls which Exchange cluster IDs HoneyMesh accepts Exchange feed data from. - `mesh.trusted_networks` controls how much HoneyMesh trusts a cluster after it becomes part of the trusted mesh workflow. - HoneyMesh omits its own cluster ID from discovered external Exchange networks. --- **7. Dashboard Layout** The dashboard is a single-page operator console. Header: - Cluster ID - License status pill - Mode controls: `TEST MODE`, `ENFORCE`, `LOCKDOWN` Main panels: - `TRAPS` - `INTERFACES` - `HONEYMESH DEFENSE NETWORK` - `LIVE THREAT STREAM` Status summaries: - License state - `Trusted Sharing` state - `Trusted Mesh Networks` state - Exchange connection details The UI now exposes whether the node is actually connected to HoneyMesh Exchange, not just whether the toggle is turned on. --- **8. Traps Panel** Purpose: - Configure honeypot listeners. - Tune local scan thresholds. - Observe trap status quickly. Controls: - Trap enable/disable - Watchdog mode - Banner editing - Scan threshold save controls Trap states shown in the UI: - `LISTENING` - `WATCHDOG` - `DISABLED` --- **9. Interfaces Panel** Purpose: - Attach and detach XDP enforcement from local interfaces. Per-interface controls: - `ATTACH` - `DETACH` Displayed fields: - Assigned IPs - Link status - Protection mode --- **10. HoneyMesh Defense Network Panel** Purpose: - Manage local sharing state. - Review trusted mesh posture. - Generate invites. - Join approved networks. Header actions: - `TRUST LEVELS` - `TRUSTED PEERS` - `TEMPORARY MESH INVITE` - `JOIN WITH INVITE` Status area: - Current license state - Exchange sharing state - Trusted mesh participation state - Exchange connectivity from `/api/health` --- **11. Trusted Peers Modal** This is now the main shared-defense control surface. Sections include: - `Enable Trusted Sharing` - `HoneyMesh Exchange Trust` - `Enable Trusted Mesh Participation` - `Temporary Mesh Invite` - `Join With Invite` - Base allowlist toggle - Allowlist editor - Trusted peer editor Exchange-specific details shown in the modal: - Real connection status: `Connected to HoneyMesh Exchange` or `Not connected to HoneyMesh Exchange` - Local cluster ID - Trusted Exchange cluster IDs - Observed Exchange cluster IDs Observed Exchange cluster IDs: - Are discovered through exchange traffic. - Do not include this node’s own cluster ID. - Can be reviewed before any trust decision is made. Trusted Exchange cluster IDs: - Control which Exchange-originated cluster feeds HoneyMesh will accept. - Are useful when you want Exchange discovery but do not want to trust every connected cluster. Save behavior: - The sharing toggle now returns the real backend error if Exchange bootstrap fails. - When Exchange bootstrap succeeds, HoneyMesh stores the returned node ID, tenant ID, and shared secret automatically. --- **12. Trusted Mesh Networks** Trusted mesh networks are cluster-level trust policies for peer federation. HoneyMesh lets operators assign: - `L0 OBSERVE` - `L1 FEDERATED` - `L2 TRUSTED` - `L3 AUTHORITATIVE` How to use them: - Discover candidate cluster IDs through HoneyMesh Exchange. - Add a cluster to trusted mesh policy. - Set the trust level that matches your operational relationship. - Use a temporary invite token to join approved peer networks. Practical model: - Exchange is for discovery and optional shared intelligence. - Trusted mesh is for explicit peer-to-peer defense cooperation. - The operator stays in control of both. --- **13. Temporary Mesh Invites** Temporary invites are the safe way to join another HoneyMesh network without handing out permanent admin credentials. Generation: - Open `TRUSTED PEERS` - Use `TEMPORARY MESH INVITE` - Choose a short TTL - Copy the token Join workflow: - Open `JOIN WITH INVITE` - Enter the peer address and token - HoneyMesh performs the join against the remote mesh endpoint API examples: Create invite: ```bash curl -k -X POST "https://:/api/mesh/invite" \ -H "X-Honey-Token: " \ -H "Content-Type: application/json" \ -d '{"ttl_minutes":30}' ``` Join with invite: ```bash curl -k -X POST "https://:/api/mesh/join" \ -H "X-Honey-Token: " \ -H "Content-Type: application/json" \ -d '{"peer":":9000","token":""}' ``` --- **14. Live Threat Stream** Purpose: - Review recent hostile activity. - Inspect active bans. - Perform manual operator actions. Events table columns: - `TIME` - `IP ADDRESS` - `PORT` - `JA4 / JA3 LEGACY` - `APP` - `SESSION` - `ACTION` Active bans table columns: - `IP` - `EXPIRES` - `JA4 / JA3 LEGACY` - `ACTION` Common actions: - `BLOCK` - `ALLOW` - `WHITELIST` - `RELEASE` - `EXTEND` - `PERMANENT` --- **15. JA4-First Fingerprinting** HoneyMesh is JA4-first. Behavior: - JA4 is the primary TLS fingerprint in the UI and shared-defense paths. - JA3 remains available as a compatibility field when present. - Shared intelligence can carry JA4 plus legacy JA3 context. - Remote data is only accepted after signature, replay-window, version, and rate-limit checks pass. --- **16. API Endpoints** Common operator endpoints: - `GET /api/health` - `GET /api/events` - `GET /api/bans` - `GET /api/bans/meta` - `GET /api/license-info` - `GET /api/security` - `GET /api/peers` - `POST /api/license` - `POST /api/security` - `POST /api/mode` - `POST /api/ban` - `POST /api/ban/extend` - `POST /api/ban/release` - `POST /api/allow` - `POST /api/trap` - `GET /api/ifaces` - `POST /api/iface` - `POST /api/mesh/invite` - `POST /api/mesh/join` - `POST /api/mesh/revoke` `POST /api/security` is the main persistence endpoint for: - allowlist settings - trusted peers - scan thresholds - Exchange sharing enablement - trusted Exchange cluster IDs - trusted mesh network policies - trusted mesh participation enablement Headers: - `X-Honey-Token: ` --- **17. Troubleshooting** Startup problems: - `failed to raise memlock limit`: run as root or raise memlock. - `license invalid` or `license expired`: HoneyMesh falls back to Community mode and disables Pro-only shared defense features. Exchange toggle fails: - Check that the node has a valid Pro license. - Confirm outbound HTTPS reachability to the configured Exchange host. - Check the exact error shown in the `TRUSTED PEERS` modal. - If bootstrap fails, HoneyMesh now surfaces the backend error directly instead of a generic save failure. Not connected to HoneyMesh Exchange: - The toggle can be on while connectivity is still broken. - Check `/api/health` and the Exchange status line in the modal. - Verify `exchange.base_url`, `exchange.node_id`, `exchange.tenant_id`, and `exchange.shared_secret` in config after successful bootstrap. No discovered networks: - Exchange discovery only shows up after Exchange traffic returns other cluster IDs. - Your own cluster ID is intentionally omitted from discovered external networks. Trusted mesh join issues: - Verify Pro mode. - Verify `trusted_mesh_network_enabled` is on. - Verify peer reachability and certificate trust. - Verify the invite token is still valid. UI not updating: - Verify the admin token. - Check browser console errors. - Refresh `/api/health` and `/api/security` directly to confirm backend state. --- **18. Operational Notes** Security posture: - XDP enforcement blocks traffic before it reaches the normal OS network stack. - Exchange and trusted mesh are both opt-in. - Shared signals are signed, replay-window checked, and rate limited. - HoneyMesh federation is version-gated and rejects invalid or stale remote intelligence. Operational guidance: - Use Exchange to discover candidate cluster IDs. - Use trusted mesh levels to formalize how much you trust another network. - Use temporary invite tokens for onboarding instead of long-lived admin secrets. - Keep Community nodes local-only unless you intentionally upgrade them. --- **19. Quick Reference** Common actions: - `TEST MODE`: detect only - `ENFORCE`: active blocking - `LOCKDOWN`: aggressive enforcement - `Trusted Sharing`: opt in to HoneyMesh Exchange - `Trusted Mesh Networks`: opt in to direct peer federation - `L0`: observe only - `L1`: limited federated trust - `L2`: trusted federated network - `L3`: authoritative network - `BLOCK`: manually ban from events - `PERMANENT`: apply long-lived ban - `RELEASE`: remove a ban