Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

DaemonEye Architecture Overview

Three-Component Security Architecture

DaemonEye implements a workspace-based architecture with multiple crates and binaries using feature flags for precise dependency control. The system follows a three-component security design with strict privilege separation to provide continuous process monitoring and threat detection. The system is designed around the principle of minimal attack surface while maintaining high performance and audit-grade integrity.

The architecture is built on the collector-core framework, which provides extensible collection infrastructure for multiple monitoring components while maintaining shared operational foundation. See the Collector-Core Framework documentation for detailed information about the underlying collection infrastructure.

The fuller, maintained architecture reference lives in System Architecture. This page is a high-level overview.

graph TB
    subgraph "DaemonEye Three-Component Architecture"
        subgraph "procmond (Privileged Collector)"
            PM[Process Monitor]
            HC[Hash Computer]
            AL[Audit Logger]
            EB1[EventBus Client]
        end

        subgraph "daemoneye-agent (Detection Orchestrator)"
            DE[Detection Engine]
            AM[Alert Manager]
            RM[Rule Manager]
            IPC2[IPC Server]
            NS[Network Sinks]
            BROKER[Embedded EventBus Broker]
        end

        subgraph "daemoneye-cli (Operator Interface)"
            QE[Query Executor]
            HC2[Health Checker]
            DM[Data Manager]
            IPC1[IPC Client]
        end

        subgraph "daemoneye-lib (Shared Core)"
            CFG[Configuration]
            MOD[Models]
            STO[Storage]
            DET[Detection]
            ALT[Alerting]
            CRY[Crypto]
        end

        subgraph "daemoneye-eventbus (Event Bus)"
            TOPICS[Topic Hierarchy]
            TRANS[Cross-Platform Transport]
        end
    end

    subgraph "Data Stores"
        ES[Event Store<br/>redb]
        AL2[Audit Ledger<br/>BLAKE3 hash-chained]
    end

    subgraph "External Systems"
        SIEM[SIEM Systems]
        WEBHOOK[Webhooks]
        SYSLOG[Syslog]
    end

    EB1 <--> BROKER
    BROKER <--> TOPICS
    BROKER <--> TRANS
    BROKER --> DE
    HC --> EB1
    AL --> AL2
    IPC1 <--> IPC2
    DE --> AM
    AM --> NS
    NS --> SIEM
    NS --> WEBHOOK
    NS --> SYSLOG
    QE --> IPC1
    HC2 --> IPC1
    DM --> IPC1
    DE --> ES

Component Responsibilities

procmond (Privileged Process Collector)

Primary Purpose: Minimal privileged component for secure process data collection with purpose-built simplicity.

Key Responsibilities:

  • Process Enumeration: Cross-platform process data collection using sysinfo crate
  • Executable Hashing: SHA-256 hash computation for integrity verification
  • Audit Logging: BLAKE3 hash-chained audit ledger (Merkle inclusion proofs In Progress)
  • EventBus Communication: Publishes process events through the embedded daemoneye-eventbus broker hosted by daemoneye-agent

Security Boundaries:

  • Starts with minimal privileges, optionally requests enhanced access
  • Drops all elevated privileges immediately after initialization
  • No network access whatsoever
  • No SQL parsing or complex query logic
  • Write-only access to audit ledger
  • Simple protobuf IPC only (Unix sockets/named pipes)

Key Interfaces:

#[async_trait]
pub trait ProcessCollector {
    async fn enumerate_processes(&self) -> Result<Vec<ProcessRecord>>;
    async fn handle_detection_task(&self, task: DetectionTask) -> Result<DetectionResult>;
    async fn serve_ipc(&self) -> Result<()>;
}

daemoneye-agent (Detection Orchestrator)

Primary Purpose: User-space detection rule execution, alert management, and procmond lifecycle management.

Key Responsibilities:

  • Detection Engine: SQL-based rule execution with security validation
  • Alert Management: Alert generation, deduplication, and delivery
  • Rule Management: Rule loading, validation, and hot-reloading
  • Process Management: procmond lifecycle management (start, stop, restart, health monitoring)
  • Network Communication: Outbound-only connections for alert delivery

Security Boundaries:

  • Operates in user space with minimal privileges
  • Manages redb event store (read/write access)
  • Translates complex SQL rules into simple protobuf tasks for procmond
  • Outbound-only network connections for alert delivery
  • Sandboxed rule execution with resource limits
  • IPC client for communication with procmond

Key Interfaces:

#[async_trait]
pub trait DetectionEngine {
    async fn execute_rules(&self, scan_id: i64) -> Result<Vec<Alert>>;
    async fn validate_sql(&self, query: &str) -> Result<ValidationResult>;
}

#[async_trait]
pub trait AlertManager {
    async fn generate_alert(&self, detection: DetectionResult) -> Result<Alert>;
    async fn deliver_alert(&self, alert: &Alert) -> Result<DeliveryResult>;
}

daemoneye-cli (Operator Interface)

Primary Purpose: Command-line interface for queries, management, and diagnostics.

Key Responsibilities:

  • Data Queries: Safe SQL query execution with parameterization
  • System Management: Configuration, rule management, health monitoring
  • Data Export: Multiple output formats (JSON, table, CSV)
  • Diagnostics: System health checks and troubleshooting

Security Boundaries:

  • No network access
  • No direct database access (communicates through daemoneye-agent)
  • Input validation for all user-provided data
  • Safe SQL execution via daemoneye-agent with prepared statements
  • Communicates only with daemoneye-agent for all operations

Key Interfaces:

#[async_trait]
pub trait QueryExecutor {
    async fn execute_query(&self, query: &str, params: &[Value]) -> Result<QueryResult>;
    async fn export_data(&self, format: ExportFormat, filter: &Filter) -> Result<ExportResult>;
}

daemoneye-lib (Shared Core)

Primary Purpose: Common functionality shared across all components.

Key Modules:

  • config: Hierarchical configuration management
  • models: Core data structures and serialization
  • storage: Database abstractions and connection management
  • detection: SQL validation and rule execution framework
  • alerting: Multi-channel alert delivery system
  • crypto: Cryptographic functions for audit chains
  • telemetry: Observability and metrics collection

Data Flow Architecture

The system implements a pipeline processing model with clear phases and strict component separation:

1. Collection Phase

sequenceDiagram
    participant SA as daemoneye-agent
    participant EB as Embedded EventBus Broker
    participant PM as procmond
    participant SYS as System

    SA->>EB: DetectionTask(ENUMERATE_PROCESSES)
    EB->>PM: Route task to collector
    PM->>SYS: Enumerate processes
    SYS-->>PM: Process data
    PM->>PM: Compute hashes
    PM->>PM: Write to audit ledger
    PM-->>EB: DetectionResult(processes)
    EB-->>SA: Route result to agent

2. Detection Phase

sequenceDiagram
    participant DE as Detection Engine
    participant DB as Event Store
    participant RM as Rule Manager

    DE->>RM: Load detection rules
    RM-->>DE: SQL rules
    DE->>DB: Execute SQL queries
    DB-->>DE: Query results
    DE->>DE: Generate alerts
    DE->>DB: Store alerts

3. Alert Delivery Phase

sequenceDiagram
    participant AM as Alert Manager
    participant S1 as Sink 1
    participant S2 as Sink 2
    participant S3 as Sink 3

    AM->>S1: Deliver alert (parallel)
    AM->>S2: Deliver alert (parallel)
    AM->>S3: Deliver alert (parallel)
    S1-->>AM: Delivery result
    S2-->>AM: Delivery result
    S3-->>AM: Delivery result

IPC Protocol Design

Purpose: Secure, efficient task/result message contract exchanged between procmond and daemoneye-agent. These protobuf messages are routed through the embedded daemoneye-eventbus broker; the interprocess IPC transport primarily carries daemoneye-cli to daemoneye-agent traffic.

Protocol Specification:

syntax = "proto3";

// Simple detection tasks sent from daemoneye-agent to procmond
message DetectionTask {
    string task_id = 1;
    TaskType task_type = 2;
    optional ProcessFilter process_filter = 3;
    optional HashCheck hash_check = 4;
    optional string metadata = 5;
}

enum TaskType {
    ENUMERATE_PROCESSES = 0;
    CHECK_PROCESS_HASH = 1;
    MONITOR_PROCESS_TREE = 2;
    VERIFY_EXECUTABLE = 3;
}

// Results sent back from procmond to daemoneye-agent
message DetectionResult {
    string task_id = 1;
    bool success = 2;
    optional string error_message = 3;
    repeated ProcessRecord processes = 4;
    optional HashResult hash_result = 5;
}

Transport Layer:

  • Unix domain sockets on Linux/macOS
  • Named pipes on Windows
  • Async message handling with tokio
  • Connection authentication and encryption (optional)
  • Automatic reconnection with exponential backoff

Database Architecture

Event Store (redb)

  • Purpose: High-performance process data storage
  • Access: daemoneye-agent read/write, daemoneye-cli read-only
  • Features: WAL mode, concurrent access, embedded database
  • Schema: process_snapshots, scans, detection_rules, alerts

Audit Ledger (BLAKE3 hash-chained)

  • Purpose: Tamper-evident audit trail using a BLAKE3 hash-chained ledger
  • Access: procmond write-only
  • Features: Per-entry BLAKE3 hash chaining with optional Ed25519 signatures
  • Implementation: rs-merkle scaffolding present; Merkle inclusion proofs are In Progress

Security Architecture

Privilege Separation

  • Only procmond runs with elevated privileges when necessary
  • Immediate privilege drop after initialization
  • Detection and alerting run in user space
  • Component-specific database access patterns

SQL Injection Prevention

  • AST validation using sqlparser crate
  • Prepared statements and parameterized queries only
  • Sandboxed detection rule execution with resource limits
  • Query whitelist preventing data modification operations

Resource Management

  • Bounded channels with configurable backpressure policies
  • Memory budgets with cooperative yielding
  • Timeout enforcement and cancellation support
  • Circuit breakers for external dependencies

Performance Characteristics

Process Collection

  • Baseline: <5 seconds for 10,000+ processes
  • CPU Usage: <5% sustained during continuous monitoring
  • Memory Usage: <100MB resident under normal operation
  • Hash Computation: SHA-256 for all accessible executables

Detection Engine

  • Rule Execution: <100ms per detection rule
  • SQL Validation: AST parsing and validation
  • Resource Limits: 30-second timeout, memory limits
  • Concurrent Execution: Parallel rule processing

Alert Delivery

  • Multi-Channel: Parallel delivery to multiple sinks
  • Reliability: Circuit breakers and retry logic
  • Performance: Non-blocking delivery with backpressure
  • Monitoring: Delivery success rates and latency metrics

Cross-Platform Strategy

Process Enumeration

  • Phase 1: sysinfo crate for unified cross-platform baseline
  • Phase 2: Platform-specific enhancements (eBPF, ETW, EndpointSecurity)
  • Fallback: Graceful degradation when enhanced features unavailable

Privilege Management

  • Linux: CAP_SYS_PTRACE, immediate capability dropping
  • Windows: SeDebugPrivilege, token restriction after init
  • macOS: Minimal entitlements, sandbox compatibility

Component Communication

procmond ↔ daemoneye-agent

  • Protocol: Protobuf messages routed through the embedded daemoneye-eventbus broker hosted by daemoneye-agent (not direct point-to-point IPC)
  • Direction: Pub/sub task/result pattern over the broker’s topic hierarchy
  • Security: Process isolation, no network access

daemoneye-agent ↔ daemoneye-cli

  • Protocol: Protobuf over Unix sockets/named pipes (interprocess IPC)
  • Direction: daemoneye-cli queries daemoneye-agent
  • Security: Local communication only, input validation

External Communication

  • Alert Delivery: Outbound-only network connections to configured sinks
  • SIEM Integration: HTTPS + webhook protocols for alert forwarding

Error Handling Strategy

Graceful Degradation

  • Continue operation when individual components fail
  • Fallback mechanisms for enhanced features
  • Circuit breakers for external dependencies
  • Comprehensive error logging and monitoring

Recovery Patterns

  • Automatic retry with exponential backoff
  • Health checks and component restart
  • Data consistency verification
  • Audit trail integrity validation

This architecture provides a robust foundation for implementing DaemonEye’s core monitoring functionality while maintaining security, performance, and reliability requirements across all supported platforms.