andreicscs-HoneyWire/Docs/Provisioning.md

HoneyWire Hub Deployment Architecture

Overview

HoneyWire uses a centralized Hub to manage node provisioning, sensor configuration, deployment generation, and configuration reconciliation.

Each managed infrastructure node receives:

• a unique Node ID
• a generated Node API Key
• a dynamic deployment bundle generated by the Hub

The Hub acts as the single source of truth for all deployed sensors and runtime configuration state.

---

Node Provisioning

Create Node

Endpoint

POST /api/v1/nodes

Purpose

Creates a new logical infrastructure node inside the HoneyWire fleet.

Request

{
  "alias": "smb-gateway",
  "tags": ["production", "gateway"]
}

Response

{
  "nodeId": "node-e0d6d6ca",
  "apiKey": "hw_key_xxxxxxxxx",
  "alias": "smb-gateway"
}

Result

The Hub creates:

• a persistent node identity
• a unique API key
• an empty deployment state

No sensors are deployed at this stage.

---

Sensor Deployment

Add Sensor to Node

Endpoint

POST /api/v1/nodes/{id}/sensors

Purpose

Assigns a sensor configuration to a node.

Request

{
  "sensorId": "hw-sensor-tcp-tarpit",
  "customName": "Credential Trap",
  "configValues": {
    "HW_DECOY_PORTS": "2222,3306",
    "HW_TARPIT_MODE": "hold"
  }
}

Result

The Hub:

• stores the sensor configuration
• links the sensor to the node
• marks the node as requiring synchronization

---

Configuration State

Pending Configuration

Whenever sensors are:

• added
• removed
• edited

the Hub sets:

nodes.pending_config = true

This indicates the deployed infrastructure configuration no longer matches the desired configuration stored in the Hub.

---

Configuration Revisions

Every generated deployment bundle receives a unique configuration revision:

HW_CONFIG_REV=rev_xxxxxxxx

rev_xxxxxxxx is a deterministic 8-char string for tracking config state.

This revision is embedded into all deployed sensors.

Purpose

Configuration revisions allow the Hub to:

• detect deployment drift
• verify successful synchronization
• reconcile desired vs active state

---

Active Revision

Once deployed sensors begin reporting heartbeats with the expected revision:

nodes.active_revision = desired_revision
nodes.pending_config = false

The node is considered synchronized.

---

Deployment Generation

Canonical Deployment Endpoint

Endpoint

GET /api/v1/nodes/compose

Authentication

Authorization: Bearer <NODE_API_KEY>

Purpose

Generates the canonical deployment bundle for the authenticated node.

The Hub:

• authenticates the node via API key
• loads installed sensors from the database
• loads manifests from the sensor catalog
• merges persisted sensor configuration
• injects runtime variables
• injects the current configuration revision
• generates the final Docker Compose deployment

---

Generated Deployment Characteristics

Generated deployments include:

• hardened container defaults
• read-only filesystems
• dropped Linux capabilities
• sensor-specific privileges only
• logging policies
• network configuration
• deployment dependencies
• runtime configuration variables

The deployment endpoint does not mark a node as synchronized.

Synchronization only occurs after sensors successfully reconnect and report the expected configuration revision through heartbeats.

---

Authentication Model

Node Authentication

HoneyWire uses API-key-based node authentication.

Nodes authenticate using:

Authorization: Bearer <NODE_API_KEY>

The Hub derives node identity internally from the API key.

Sensors never provide or control their own Node ID.

---

Sensor Runtime Variables

Sensors only require the following runtime variables:

HW_HUB_ENDPOINT
HW_HUB_KEY
HW_SENSOR_ID
HW_CONFIG_REV
HW_TEST_MODE

Node identity is resolved server-side by the Hub.

---

Manual Deployment Workflow

Typical Operator Flow

1. Create Node

The operator creates a node through the Fleet UI.

2. Configure Sensors

Sensors are selected from the Sensor Catalog and assigned to the node.

3. Generate Deployment

The node retrieves its deployment bundle from:

GET /api/v1/nodes/compose

4. Deploy Compose Stack

The generated compose file is deployed to the target infrastructure host.

5. Reconciliation

Sensors begin sending authenticated heartbeats containing:

HW_CONFIG_REV

The Hub validates the revision and marks the node as synchronized.

---

Preview vs Deployment

Feature	Preview Generator	Node Deployment
Endpoint	POST /api/v1/compose/generate	GET /api/v1/nodes/compose
Purpose	UI compose preview	Production deployment generation
Authentication	UI Session	Node API Key
State Tracking	No	Yes
Revision Injection	No	Yes
Database-backed	No	Yes

---

Architecture Summary

HoneyWire follows a centralized reconciliation architecture:

• the Hub stores desired infrastructure state
• nodes authenticate using API keys
• deployments are generated dynamically
• sensors report active runtime revisions
• synchronization is verified through telemetry

This ensures:

• deterministic deployments
• drift detection
• centralized configuration management
• secure node authentication
• reproducible infrastructure state