vm-control/docs/EVENT_GENERATION.md

VaultMesh Command Center: Event Generation Mechanism

Overview

The VaultMesh Command Center generates events through a sophisticated, multi-layered mechanism designed for real-time monitoring and fleet management.

Event Types

1. Heartbeat Events

• Trigger: Node heartbeat submission
• Payload Includes:
  • Timestamp
  • Node ID
  • Hostname
  • OS Profile
  • Cloudflare Status
  • Services Status
  • VaultMesh Root Path
  • System Metrics (uptime, load averages)

2. Scan Events

• Trigger: Successful scan result submission
• Payload Includes:
  • Timestamp
  • Node ID
  • Hostname
  • OS Profile
  • Scan Summary (critical/high/medium/low findings)
  • Real/Mock Findings Flag
  • Receipt Hash

3. Command Events

• Trigger: Command execution result
• Payload Includes:
  • Timestamp
  • Node ID
  • Hostname
  • OS Profile
  • Command Name
  • Execution Status
  • Exit Code
  • Nonce (for replay protection)

Event Generation Flow

1. Data Collection

   • Node agents submit heartbeats and scan results
   • Command results are reported back to the Command Center

2. Event Processing

   • Raw data is transformed into structured event payloads
   • Events are published to a broadcast channel
   • Server-Sent Events (SSE) distribute events to connected clients

3. State Management

   • Events trigger state updates (node history, last scan, etc.)
   • Attention status is recomputed based on new events

Advanced Features

• Automatic Scan Scheduling

  • Periodic scans triggered based on node profile and last scan timestamp
  • Configurable scan intervals

• Attention Computation

  • Dynamic assessment of node health
  • Tracks critical findings, heartbeat staleness, service status

Security Considerations

• Ed25519 key signing for commands
• Nonce-based replay protection
• Configurable command policies per node profile

Performance Characteristics

• In-memory event storage (500 most recent events)
• Optional JSONL log persistence
• Low-overhead event broadcasting

Extensibility

The event system supports easy addition of new event types and payloads through the ServerEvent enum and corresponding payload structures.