DaemonEye EventBus Topic Hierarchy#

This document describes the complete topic hierarchy for the DaemonEye EventBus, including event topics, control topics, and health monitoring topics.

Overview#

The DaemonEye EventBus uses a hierarchical topic structure to organize messages between components. Topics are organized into two main domains:

• Event Topics (events.*) - Data flow from collectors to the agent
• Control Topics (control.*) - Management and coordination messages

Topic Structure#

Topics follow a hierarchical naming convention with up to 4 levels:

<domain>.<subdomain>.<type>[.<subtype>]

For example:

• events.process.lifecycle - Process lifecycle events
• control.collector.config - Collector configuration updates
• control.health.heartbeat - Health monitoring heartbeats

Wildcard Support#

The EventBus supports two types of wildcards for flexible subscriptions:

• Single-level wildcard (+): Matches exactly one segment

  • Example: events.+.lifecycle matches events.process.lifecycle and events.network.lifecycle

• Multi-level wildcard (#): Matches one or more remaining segments (must be the final segment)

  • Example: events.process.# matches all process events
  • Example: control.# matches all control messages
  • Note: # requires at least one remaining segment — events.# does not match the bare single-segment topic events.

Matcher behavior is locked by a truth-table test#

The exact wildcard-matching semantics above are codified by a snapshot truth-table test, so they cannot drift silently:

• Test: daemoneye-eventbus/tests/pattern_truth_table.rs
• Snapshot: daemoneye-eventbus/tests/snapshots/pattern_truth_table__topic_pattern_matrix_v1.snap
• Run/update: cargo test -p daemoneye-eventbus -- tests::pattern_truth_table, then cargo insta review

Event Topics#

Event topics carry data from monitoring collectors to the daemoneye-agent for analysis and detection.

Process Events (events.process.*)#

Process monitoring events from procmond:

Wildcard Pattern: events.process.# - Subscribe to all process events

Network Events (events.network.*)#

Network monitoring events from netmond (future extension):

Wildcard Pattern: events.network.# - Subscribe to all network events

Filesystem Events (events.filesystem.*)#

Filesystem monitoring events from fsmond (future extension):

Wildcard Pattern: events.filesystem.# - Subscribe to all filesystem events

Performance Events (events.performance.*)#

Performance monitoring events from perfmond (future extension):

Wildcard Pattern: events.performance.# - Subscribe to all performance events

Control Topics#

Control topics manage collector lifecycle, configuration, and health monitoring.

Collector Management (control.collector.*)#

Collector lifecycle and configuration management:

Wildcard Pattern: control.collector.# - Subscribe to all collector control messages

Agent Orchestration (control.agent.*)#

Agent-level orchestration and policy management:

Wildcard Pattern: control.agent.# - Subscribe to all agent control messages

Health Monitoring (control.health.*)#

Component health monitoring and diagnostics:

Wildcard Pattern: control.health.# - Subscribe to all health messages

Access Control#

Topics have three access levels that control who can publish and subscribe:

Public Topics#

• Accessible to all components
• Examples: control.health.*, events.*.anomaly
• No authentication required

Restricted Topics#

• Component-specific access
• Examples: events.process.*, control.collector.task, control.collector.task.*.*
• Requires component registration

Privileged Topics#

• Requires authentication
• Examples: control.collector.lifecycle, control.agent.policy
• Only daemoneye-agent can publish

Usage Examples#

Subscribing to Process Events#

use daemoneye_eventbus::{EventBus, EventSubscription, SourceCaps, process};

// Subscribe to all process events
let subscription = EventSubscription {
    subscriber_id: "my-subscriber".to_string(),
    capabilities: SourceCaps {
        event_types: vec!["process".to_string()],
        collectors: vec!["procmond".to_string()],
        max_priority: 5,
    },
    event_filter: None,
    correlation_filter: None,
    topic_patterns: Some(vec![process::ALL.to_string()]),
    enable_wildcards: true,
};

let mut receiver = event_bus.subscribe(subscription).await?;

Publishing to a Specific Topic#

use daemoneye_eventbus::{EventBus, CollectionEvent, ProcessEvent, process};
use std::collections::HashMap;

// Publish a process lifecycle event
let event = CollectionEvent::Process(ProcessEvent {
    pid: 1234,
    name: "example".to_string(),
    command_line: Some("example --arg".to_string()),
    executable_path: Some("/bin/example".to_string()),
    ppid: Some(1),
    start_time: Some(std::time::SystemTime::now()),
    metadata: HashMap::new(),
});

// The broker will route this to events.process.new
event_bus.publish(event, "correlation-id".to_string()).await?;

Using the Topic Builder#

use daemoneye_eventbus::TopicBuilder;

// Build a topic programmatically
let topic = TopicBuilder::events()
    .process()
    .lifecycle()
    .build();

assert_eq!(topic, "events.process.lifecycle");

// Build and validate
let validated_topic = TopicBuilder::control()
    .collector()
    .config()
    .build_validated()?;

Checking Access Levels#

use daemoneye_eventbus::{TopicHierarchy, TopicAccessLevel, process, collector};

// Check access level for a topic
let level = TopicHierarchy::get_access_level(process::LIFECYCLE);
assert_eq!(level, TopicAccessLevel::Restricted);

let level = TopicHierarchy::get_access_level(collector::LIFECYCLE);
assert_eq!(level, TopicAccessLevel::Privileged);

Topic Naming Conventions#

When creating new topics, follow these conventions:

1. Use lowercase: All topic segments must be lowercase
2. Use hyphens for multi-word segments: events.process.parent-child (if needed)
3. Keep it hierarchical: Organize from general to specific
4. Be descriptive: Topic names should clearly indicate their purpose
5. Avoid deep nesting: Maximum 4 levels (domain.subdomain.type.subtype)

Security Boundaries#

The topic hierarchy enforces security boundaries:

1. Collectors can only publish to their domain-specific event topics

   • procmond → events.process.*
   • netmond → events.network.*
   • fsmond → events.filesystem.*
   • perfmond → events.performance.*

2. daemoneye-agent can publish to all control topics

   • control.collector.*
   • control.agent.*

3. All components can publish health messages

   • control.health.*

4. Subscription filtering ensures components only receive relevant events

   • Based on capabilities and topic patterns
   • Enforced by the broker

Future Extensions#

The topic hierarchy is designed to be extensible. Future additions may include:

• Trigger Topics (control.trigger.*) - For triggerable collectors
• Analysis Topics (events.analysis.*) - For analysis results
• Correlation Topics (events.correlation.*) - For multi-domain correlation
• Security Topics (events.security.*) - For security-specific events

References#

• Topic Implementation - Core topic matching and validation
• Topics Module - Complete topic hierarchy definitions
• Broker Implementation - Message routing and delivery
• Design Document - Architecture overview