Project Overview

Codebase Metrics

Crate Size Breakdown

Architecture Overview

Design Principles

• Offline-First: Complete air-gap compatibility, zero external dependencies at runtime
• Privilege Separation: Only procmond runs elevated; detection and alerting are user-space
• Security-First: unsafe_code = "forbid" at workspace level, zero-warning clippy policy
• Operator-Focused: Built for security professionals in contested/airgapped environments
• Trait-Based Extensibility: All major subsystems use trait abstractions for pluggability
• Async-First: Tokio-based with streaming APIs to prevent unbounded memory buffering

Technology Stack

Three-Component Security Architecture

DaemonEye implements strict privilege separation across three binaries with distinct security boundaries. Each component operates at a different privilege level with carefully controlled data access and network capabilities.

Component Privilege Matrix

Deployment Tiers

Data Flow Pipeline

The system follows a pipeline processing model where process data flows from collection through detection to alerting. Each stage enforces security boundaries and uses bounded channels for backpressure.

procmond: Privileged Process Collector

Overview

procmond is the privileged component responsible for process enumeration, lifecycle tracking, and audit trail maintenance. It runs with elevated privileges only during initialization, then drops to minimal permissions. It has zero network access and communicates solely via local IPC.

Execution Modes

procmond operates in two modes determined by the DAEMONEYE_BROKER_SOCKET environment variable:

Actor Mode (env var set — managed by daemoneye-agent):

• Constructs ProcmondMonitorCollector with EventBusConnector

• Spawns four concurrent Tokio tasks: backpressure monitor, heartbeat (30s interval), shutdown handler, event consumer

• Buffer management: 10MB max buffer, backpressure activates at 70% (7MB), releases at 50% (5MB)
  Standalone Mode (env var unset — independent operation):

• Uses ProcessEventSource with collector-core framework

• Registration timeout: 10s, max 3 retries with exponential backoff

Process Collection

The ProcessCollector trait provides cross-platform process enumeration:

pub trait ProcessCollector: Send + Sync {
    fn name(&self) -> &'static str;
    fn capabilities() -> ProcessCollectorCapabilities;
    async fn collect_processes() -> Result<(Vec<ProcessEvent>, CollectionStats)>;
    async fn collect_process(pid: u32) -> Result<ProcessEvent>;
    async fn health_check() -> Result<()>;
}

Platform implementations: linux_collector.rs, macos_collector.rs, windows_collector.rs

ProcessCollectionConfig defaults: enhanced_metadata=true, compute_hashes=false, max_processes=unlimited, skip_system=false, skip_kernel=false

Process Lifecycle Tracking

The lifecycle tracker (lifecycle.rs) detects four event types:

PID Reuse Handling: Compares start times to detect when a new process reuses a recycled PID.

Write-Ahead Log (WAL)

The WAL (wal.rs) provides crash recovery for event publishing:

• Entry format: Sequence number (u64, monotonic) + ProcessEvent + CRC32 checksum + event type tag
• Serialization: Length-delimited postcard (no-default-features, alloc-only) with CRC32 integrity validation
• File rotation: At 80MB threshold, files named procmond-{sequence:05}.wal
• Recovery: On startup, replays all WAL files in sequence order, re-publishes unpublished events
• Confirmation: mark_published(sequence) enables cleanup after successful delivery

Security Context

Platform-specific privilege detection:

• Linux: Parses /proc/self/status CapEff field for CAP_SYS_PTRACE (bit 19) and CAP_DAC_READ_SEARCH (bit 2)
• macOS: Checks getuid() == 0
• Windows: Currently returns degraded mode (tracked in issue #149)
• FreeBSD: Checks getuid() == 0 (best-effort)
  Data Sanitization: Redacts values after sensitive flags (--password, --secret, --token, --api-key, -p, -s, -t, -k) in command lines. Sanitizes env vars containing PASSWORD, SECRET, TOKEN, KEY, API_KEY, AUTH. Redacts file paths containing .ssh, .aws, .gnupg, .kube/config, .docker/config.

Actor Model

In actor mode, ProcmondMonitorCollector communicates via an ActorHandle with a bounded mpsc channel (capacity: 100):

pub enum ActorMessage {
    HealthCheck { respond_to: oneshot::Sender<HealthCheckData> },
    UpdateConfig { config: Box<ProcmondMonitorConfig>, respond_to: oneshot::Sender<Result<()>> },
    GracefulShutdown { respond_to: oneshot::Sender<Result<()>> },
    BeginMonitoring,
    AdjustInterval { new_interval: Duration },
}

CollectorState transitions: WaitingForAgent → Running → ShuttingDown → Stopped

daemoneye-agent: Detection Orchestrator

Overview

The agent operates in user-space with minimal privileges. It manages the embedded event bus broker, coordinates collector lifecycles via RPC, executes SQL-based detection rules, and dispatches alerts through configured sinks.

Three-Phase Startup

Phase 1 — Initialization:

• Load YAML configuration

• Initialize tracing/telemetry

• Start embedded DaemoneyeBroker

• Start IPC server for CLI communication
  Phase 2 — Collector Coordination:

• Load collectors config from /etc/daemoneye/collectors.json (Unix) or C:\ProgramData\DaemonEye\config\collectors.json (Windows)

• Wait for expected collectors to register via RPC

• State machine: Loading → Ready → SteadyState

• Broadcast BeginMonitoring to all registered collectors
  Phase 3 — Detection & Alerting:

• Initialize DetectionEngine with SQL rule evaluation

• Initialize AlertManager with configured sinks

• Main event loop: periodic RPC health checks (every 10 iterations), request process enumeration via RPC, execute detection rules, dispatch matching alerts

Agent State Machine

pub enum AgentState {
    Loading, // Spawning collectors, waiting for registration
    Ready, // All collectors registered and ready
    SteadyState, // Normal operation, monitoring broadcast
    StartupFailed { reason: String }, // Timeout or fatal error
    ShuttingDown, // Graceful shutdown in progress
}

Collector Registry

Thread-safe registry (RwLock<HashMap<String, CollectorRecord>>) managing collector lifecycles:

• Registration: Validates uniqueness, assigns topics, records heartbeat interval
• Heartbeat monitoring: 30s default interval, 3 max missed heartbeats, 10% grace period
• Recovery detection: Identifies collectors with HeartbeatStatus::Failed for restart

IPC Server

Listens for CLI connections via InterprocessServer. Receives DetectionTask messages and returns DetectionResult with process, network, filesystem, and performance event vectors.

daemoneye-lib: Shared Core Library

Module Architecture

Feature-gated module system for precise dependency control:

// Core modules (always available)
pub mod config;
pub mod crypto;
pub mod ipc;
pub mod models;
pub mod proto;
pub mod storage;
pub mod telemetry;

// Feature-gated modules
#[cfg(feature = "alerting")] pub mod alerting;
#[cfg(feature = "process-collection")] pub mod collection;
#[cfg(feature = "detection-engine")] pub mod detection;
#[cfg(feature = "kernel-monitoring")] pub mod kernel;
#[cfg(feature = "network-correlation")] pub mod network;

Models (models/)

Core data types shared across all components:

ProcessRecord: pid (u32), name (String), executable_path, command_line, start_time, cpu_usage (f64), memory_usage (u64), status, executable_hash (SHA-256), collection_time

Alert: id, severity (Info/Low/Medium/High/Critical), title, description, detection_rule_id, process (ProcessRecord), deduplication_key, timestamps

DetectionRule: id, name, description, sql_query, category, severity, enabled flag, validation constraints

SystemInfo: hostname, os_name, os_version, architecture, cpu_cores, total_memory, uptime, capabilities

Storage (storage.rs) — redb Integration

Five table definitions with JSON-serialized byte values:

Note: redb Value trait implementations are pending (Task 8). Current implementation uses stub methods with proper transaction scaffolding.

Detection Engine (detection/)

SQL-based detection with AST validation for injection prevention:

• sql_to_ipc.rs: Parses SQL queries using sqlparser, validates AST structure, generates IPC DetectionTask messages
• Security: Whitelist-based function approval, SELECT-only queries, no data modification operations permitted
• Sandboxing: Detection rules execute with resource limits in an isolated context

Alert System (alerting.rs)

Trait-based multi-channel alert delivery:

#[async_trait]
pub trait AlertSink: Send + Sync {
    async fn send(&self, alert: &Alert) -> Result<DeliveryResult, AlertingError>;
    fn name(&self) -> &str;
    async fn health_check(&self) -> Result<(), AlertingError>;
}

Implementations: StdoutSink (JSON/Human/CSV), FileSink (append mode), with factory pattern (AlertSinkFactory) for config-driven creation.

AlertManager provides:

• Concurrent delivery to all sinks via futures::future::join_all
• Deduplication window (default 5 minutes, configurable)
• Rate limiting (max alerts per minute)
• Automatic pruning of dedup cache at 1000 entries
• Health summary with per-sink status and percentage calculation
• Error isolation: individual sink failures don't block other deliveries

Cryptographic Subsystem (crypto.rs)

Certificate Transparency-style audit ledger:

Blake3Hasher: Computes BLAKE3 hashes (32 bytes / 64 hex chars) for data and string inputs.

AuditEntry (7 fields): sequence, timestamp, actor, action, payload_hash, previous_hash (chain link), entry_hash. Each entry's hash incorporates all fields plus the previous entry's hash, creating a tamper-evident chain.

AuditLedger: Append-only structure with add_entry(), verify_integrity() (validates both individual entry hashes and chain continuity), get_latest_hash(). Uses saturating_add for sequence numbers.

Planned: Merkle tree inclusion proofs via rs-merkle crate, Ed25519 signatures for external verification.

IPC Communication (ipc/)

Four-layer IPC architecture:

• codec.rs: Protobuf message framing with CRC32C integrity checking
• client.rs: Resilient IPC client with circuit breaker and load balancing
• interprocess_transport.rs: Unix socket (Linux/macOS) and Windows named pipe transport
• proto/ipc.proto: Detection task and result message definitions
  Transport: Unix domain sockets on Linux/macOS, named pipes (\\.\pipe\DaemonEye-broker) on Windows. Async message handling with automatic reconnection and exponential backoff.

Configuration (config.rs)

Hierarchical configuration with precedence: CLI flags > environment variables (PROCMOND_*) > user config (~/.config/procmond/config.yaml) > system config (/etc/procmond/config.yaml) > embedded defaults.

Formats: YAML, JSON, TOML via figment.

Event Bus Architecture

daemoneye-eventbus Crate

Embedded pub/sub message broker providing multi-collector coordination:

Core Components (17 modules):

• broker.rs — DaemoneyeBroker: Embedded event broker with topic-based routing
• message.rs — 12 message type variants with correlation metadata tracking
• rpc.rs — 3 traits, 21 structs for request/response patterns
• topic.rs / topics.rs — Hierarchical topic abstraction
• transport.rs — Transport layer (10 structs)
• queue_manager.rs — Per-client message queue management
• process_manager.rs — Process lifecycle (6 structs)
• task_distribution.rs — Load balancing (4 structs)
• result_aggregation.rs — Result combining (5 structs)
• correlation.rs — Distributed tracing (8 structs)
• rate_limiter.rs — Rate limiting (2 structs)
• compatibility.rs — Version compatibility (5 structs)

Topic Hierarchy

events.process.{start|stop|modify} → ProcessEvent with correlation metadata
control.health.heartbeat.{collector_id} → HeartbeatMetrics from procmond
control.collector.lifecycle → Registration/Deregistration requests
control.collector.{id} → RPC control messages to collectors
control.rpc.response → RPC responses from collectors
events.collector.{id} → Event output from specific collector

Protobuf Message Definitions

Quality of Service

The event bus supports configurable QoS:

• Delivery Guarantees: AT_MOST_ONCE, AT_LEAST_ONCE, EXACTLY_ONCE
• Duplicate Handling: Configurable deduplication strategies
• Retention Policies: Time-based and count-based message retention

Backpressure Management

• 10MB max buffer per connector
• Activation threshold: 70% capacity (7MB)
• Release threshold: 50% capacity (5MB)
• Backpressure signal reduces collection interval or pauses event processing

Collector Framework (collector-core)

Overview

Extensible collection infrastructure (22 modules, 19,398 SLOC) providing shared operational foundation for multiple monitoring components.

Key Components

Key Traits

• MonitorCollector — Generic monitoring collector interface
• HighPerformanceEventBus — High-throughput event distribution
• EventBusClient — Event bus client interface
• RpcClient — RPC communication pattern
• CollectorRpcClient — Lifecycle management (start/stop/restart/health_check/update_config)
• ResultAggregator — Multi-collector result aggregation
• ConfigManager — Configuration management interface

Security Model

Defense in Depth

Cryptographic Standards

Performance Budgets & Benchmarking

Performance Targets

Benchmark Suite (16 Criterion Suites)

Resource Management

• Bounded channels with configurable backpressure policies
• Memory budgets with cooperative yielding
• Timeout enforcement and cancellation support
• Circuit breakers for external dependencies
• Graceful degradation when resource-constrained

CI/CD Pipeline

GitHub Actions Workflows

CI Test Matrix

• Platforms: Linux (ubuntu-22.04), macOS-15, Windows (windows-2022)
• Rust: stable, beta, MSRV (1.91+)
• Quality Gate: just lint (clippy strict + fmt-check + justfile lint) must pass

Development Commands (justfile — 136 tasks)

Error Handling Architecture

Two-tier error handling strategy:

• thiserror: Structured, typed errors for library boundaries (every module defines its own #[non_exhaustive] error enum)
• anyhow: Contextual errors for binary crate orchestration and error propagation

Key Error Types

Platform Support

• macOS: security-framework 3.5.1
• Windows: windows 0.62.2 (14 Win32 features), windows-service 0.8.0, winreg 0.56.0
• Unix/FreeBSD: uzers 0.12.2, nix

Internal Dependency Graph

Testing Strategy

Three-Tier Architecture

Quality Enforcement

• Runner: cargo-nextest (parallel execution, failure isolation)
• Coverage: llvm-cov with LCOV output (target: >85%)
• Zero-Warning Policy: cargo clippy -- -D warnings with no exceptions
• Formatting: rustfmt with 119-char line length
• Environment: NO_COLOR=1 TERM=dumb cargo test --workspace for stable output

Known Technical Debt & Implementation Status

Configuration Parameters Reference

Developer Gotchas

Document Metadata