DaemonEye Documentation

Welcome to the DaemonEye documentation. DaemonEye is a high-performance, security-focused process monitoring system built in Rust. The product is pre-release; this documentation covers architecture, design, technical specifications, security, testing, and contribution guidelines.

What is DaemonEye?

DaemonEye is an agent-centric system monitoring tool designed for cybersecurity professionals, threat hunters, and security operations centers. It provides process monitoring, SQL-based threat detection, and alert delivery, with a focus on silent observation and audit-grade integrity.

Key Features

• Real-time Process Monitoring: Continuous monitoring of system processes with minimal performance impact
• SQL-Based Detection: Detection rules expressed in a SQL-like DSL with AST validation
• Cross-Platform Support: Linux and Windows primary; macOS and FreeBSD secondary
• Audit-Grade Integrity: BLAKE3 hash-chained audit ledger with Merkle-proof support (Ed25519 event signing is planned, not yet implemented)
• Air-Gap Friendly: Fully functional offline; no automatic egress
• Security-Focused: Built with security best practices and minimal attack surface

DaemonEye is distributed as open-core. This repository contains the Community tier — the agent-side foundation. Commercial-tier offerings (fleet management, GUI, federation, kernel-level collectors) extend this foundation and are sold separately through evilbitlabs.io; they are not in this repo.

Three-Component Security Architecture

DaemonEye follows a three-component security architecture:

1. procmond (Collector): Privileged process monitoring daemon built on the collector-core framework with minimal attack surface
2. daemoneye-agent (Orchestrator): User-space orchestrator with:
   • Embedded EventBus broker for multi-collector coordination via topic-based pub/sub messaging
   • RPC service for collector lifecycle management (start/stop/restart/health checks)
   • IPC server for CLI communication using protobuf over Unix sockets/named pipes
   • Alert management with multi-channel delivery
3. daemoneye-cli: Command-line interface for queries and system management

This separation ensures robust security by isolating privileged operations from network functionality while enabling scalable multi-collector architectures with RPC-based lifecycle management.

Documentation Structure

This documentation is organized into several sections:

• Getting Started: Prerequisites, privilege model, and architectural orientation
• Project Overview: Detailed project information and value propositions
• Architecture: System architecture and design principles
• Technical Documentation: Technical specifications and implementation details
• Security: Security model and design overview
• Testing: Testing strategies and guidelines
• Contributing: Contribution guidelines and development setup

Note: Installation, deployment, operator, CLI, and API reference documentation will be published with the v1.0.0 release. For the latest project status, see the repository README.

Getting Help

If you need help with DaemonEye:

1. Check the Getting Started guide
2. Review the Architecture and Technical Documentation
3. Consult the Security section for the security model
4. Join the community discussions on GitHub
5. Contact support for commercial assistance

License

The DaemonEye components in this repository — procmond, daemoneye-agent, daemoneye-cli, daemoneye-lib, collector-core, daemoneye-eventbus — are licensed under Apache 2.0. Commercial extensions ship separately; see evilbitlabs.io for details.

This documentation tracks the development state of the DaemonEye Community tier and is updated as the codebase evolves.

Getting Started with DaemonEye

This guide will help you get DaemonEye up and running quickly on your system. DaemonEye is designed to be simple to deploy while providing powerful security monitoring capabilities

Table of Contents

• Prerequisites
  • System Requirements
  • Privilege Requirements
• Installation
  • Option 1: Pre-built Binaries (Recommended)
  • Option 2: From Source
  • Option 3: Package Managers
• Quick Start
  • 1. Create Configuration Directory
  • 2. Create Basic Configuration
  • 3. Create Data Directory
  • 4. Start the Services
    • Option A: Manual Start (Testing)
    • Option B: System Service (Production)
  • 5. Verify Installation
• Basic Configuration
  • Essential Settings
  • Alert Configuration
• Creating Your First Detection Rule
  • 1. Create Rules Directory
  • 2. Create a Simple Rule
  • 3. Test the Rule
  • 4. Monitor for Alerts
• Common Operations
  • Querying Process Data
  • Managing Rules
  • System Health Monitoring
• Troubleshooting
  • Common Issues
  • Debug Mode
  • Getting Help
• Next Steps
• Support

Prerequisites

System Requirements

Minimum Requirements:

• OS: Linux (kernel 3.10+), macOS (10.14+), or Windows (10+)
• RAM: 512MB available memory
• Disk: 1GB free space
• CPU: Any x86_64 or ARM64 processor

Recommended Requirements:

• OS: Linux (kernel 4.15+), macOS (11+), or Windows (11+)
• RAM: 2GB+ available memory
• Disk: 10GB+ free space
• CPU: 2+ cores

Privilege Requirements

DaemonEye requires elevated privileges for process monitoring. The system is designed to:

1. Request minimal privileges during startup
2. Drop privileges immediately after initialization
3. Continue operating with standard user privileges

• Linux: Requires CAP_SYS_PTRACE capability (or root)
• Windows: Requires SeDebugPrivilege (or Administrator)
• macOS: Requires appropriate entitlements (or root)

Installation

Option 1: Pre-built Binaries (Recommended)

1. Download the latest release:

   # Linux (x86_64)
   wget https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/DaemonEye_Linux_x86_64.tar.gz
   tar -xzf DaemonEye_Linux_x86_64.tar.gz
   
   # Linux (ARM64)
   wget https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/DaemonEye_Linux_aarch64.tar.gz
   tar -xzf DaemonEye_Linux_aarch64.tar.gz
   
   # macOS (Intel)
   curl -L https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/DaemonEye_Darwin_x86_64.tar.gz | tar -xz
   
   # macOS (Apple Silicon)
   curl -L https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/DaemonEye_Darwin_aarch64.tar.gz | tar -xz
   
   # Windows (x86_64)
   # Download https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/DaemonEye_Windows_x86_64.zip
   # Extract the ZIP file
   
   # Windows (ARM64)
   # Download https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/DaemonEye_Windows_aarch64.zip
   # Extract the ZIP file
   

2. Install to system directories:

   # Linux/macOS
   sudo cp procmond daemoneye-agent daemoneye-cli /usr/local/bin/
   sudo chmod +x /usr/local/bin/procmond /usr/local/bin/daemoneye-agent /usr/local/bin/daemoneye-cli
   
   # Windows
   # Copy to C:\Program Files\DaemonEye\
   

Option 2: From Source

1. Install Rust (1.91+):

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   source ~/.cargo/env
   

2. Clone and build:

   git clone https://github.com/daemoneye/daemoneye.git
   cd daemoneye
   cargo build --release
   

3. Install built binaries:

   sudo cp target/release/procmond target/release/daemoneye-agent target/release/daemoneye-cli /usr/local/bin/
   

Option 3: Package Managers

Homebrew (macOS):

brew install daemoneye/daemoneye/daemoneye

APT (Ubuntu/Debian):

# Add repository (when available)
sudo apt update
sudo apt install daemoneye

YUM/DNF (RHEL/CentOS):

# Add repository (when available)
sudo yum install daemoneye

Quick Start

1. Create Configuration Directory

# Linux/macOS
sudo mkdir -p /etc/daemoneye
sudo chown $USER:$USER /etc/daemoneye

# Windows
mkdir C:\ProgramData\DaemonEye

2. Create Basic Configuration

Create a basic configuration file at /etc/daemoneye/config.yaml:

# DaemonEye Configuration
app:
  scan_interval_ms: 30000
  batch_size: 1000
  log_level: info

database:
  path: /var/lib/daemoneye/events.redb
  retention_days: 30

# EventBus broker configuration
broker:
  socket_path: /tmp/daemoneye-eventbus.sock
  startup_timeout_seconds: 30
  max_subscribers: 100
  message_buffer_size: 10000

# RPC service configuration
rpc:
  default_timeout_seconds: 30
  health_check_interval_seconds: 60
  enable_correlation_tracking: true

# Process manager configuration (for collector lifecycle)
process_manager:
  graceful_shutdown_timeout_seconds: 60
  force_shutdown_timeout_seconds: 5
  health_check_interval_seconds: 120
  enable_auto_restart: true

# Platform-specific settings
platform:
  linux:
    enable_ebpf: false  # Requires kernel 4.15+
  windows:
    enable_etw: false   # Requires Windows 10+
  macos:
    enable_endpoint_security: false  # Requires macOS 10.15+

3. Create Data Directory

# Linux/macOS
sudo mkdir -p /var/lib/daemoneye
sudo chown $USER:$USER /var/lib/daemoneye

# Windows
mkdir C:\ProgramData\DaemonEye\data

4. Start the Services

Option A: Manual Start (Testing)

# Terminal 1: Start daemoneye-agent (includes embedded EventBus broker, RPC service, and IPC server)
daemoneye-agent --database /var/lib/daemoneye/events.redb --log-level info

# The agent will:
# - Start the embedded EventBus broker for collector coordination
# - Initialize RPC service for collector lifecycle management
# - Start IPC server for CLI communication
# - Begin health monitoring and metrics collection

# Terminal 2: Use CLI for database queries and health checks
daemoneye-cli --database /var/lib/daemoneye/events.redb --format json

# Terminal 3: Run procmond directly for testing (uses collector-core framework)
# Note: In production, procmond is managed by daemoneye-agent via RPC
procmond --database /var/lib/daemoneye/events.redb --interval 30 --enhanced-metadata

Option B: System Service (Production)

# Linux (systemd)
sudo cp scripts/systemd/daemoneye.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable daemoneye
sudo systemctl start daemoneye

# macOS (launchd)
sudo cp scripts/launchd/com.daemoneye.agent.plist /Library/LaunchDaemons/
sudo launchctl load /Library/LaunchDaemons/com.daemoneye.agent.plist

# Windows (Service)
# Run as Administrator
sc create "DaemonEye Agent" binPath="C:\Program Files\DaemonEye\daemoneye-agent.exe --config C:\ProgramData\DaemonEye\config.yaml"
sc start "DaemonEye Agent"

5. Verify Installation

# Check database statistics and health
daemoneye-cli --database /var/lib/daemoneye/events.redb --format human

# View database statistics in JSON format
daemoneye-cli --database /var/lib/daemoneye/events.redb --format json

# Test procmond collection with enhanced metadata and hashing
procmond --database /var/lib/daemoneye/events.redb --interval 30 --enhanced-metadata --compute-hashes

# Check component help
daemoneye-agent --help
daemoneye-cli --help
procmond --help

Basic Configuration

Essential Settings

Scan Interval: How often to collect process data

app:
  scan_interval_ms: 30000  # 30 seconds

Database Retention: How long to keep data

database:
  retention_days: 30  # Keep data for 30 days

Log Level: Verbosity of logging

app:
  log_level: info    # debug, info, warn, error

Alert Configuration

Enable Syslog Alerts:

alerting:
  sinks:
    - type: syslog
      enabled: true
      facility: daemon
      tag: daemoneye

Enable Webhook Alerts:

alerting:
  sinks:
    - type: webhook
      enabled: true
      url: https://your-siem.com/webhook
      headers:
        Authorization: Bearer your-token

Enable File Output:

alerting:
  sinks:
    - type: file
      enabled: true
      path: /var/log/daemoneye/alerts.json
      format: json

Creating Your First Detection Rule

1. Create Rules Directory

mkdir -p /etc/daemoneye/rules

2. Create a Simple Rule

Create /etc/daemoneye/rules/suspicious-processes.sql:

-- Detect processes with suspicious names
SELECT
    pid,
    name,
    executable_path,
    command_line,
    collection_time
FROM processes
WHERE
    name IN ('malware.exe', 'backdoor.exe', 'trojan.exe')
    OR name LIKE '%suspicious%'
    OR executable_path LIKE '%temp%'
ORDER BY collection_time DESC;

3. Test the Rule

# Validate the rule
daemoneye-cli rules validate /etc/daemoneye/rules/suspicious-processes.sql

# Test the rule
daemoneye-cli rules test /etc/daemoneye/rules/suspicious-processes.sql

# Enable the rule
daemoneye-cli rules enable suspicious-processes

4. Monitor for Alerts

# Watch for new alerts
daemoneye-cli alerts watch

# List recent alerts
daemoneye-cli alerts list --limit 10

# Export alerts
daemoneye-cli alerts export --format json --output alerts.json

Common Operations

Querying Process Data

Basic Queries:

# List all processes
daemoneye-cli query "SELECT * FROM processes LIMIT 10"

# Find processes by name
daemoneye-cli query "SELECT * FROM processes WHERE name = 'chrome'"

# Find high CPU processes
daemoneye-cli query "SELECT * FROM processes WHERE cpu_usage > 50.0"

# Find processes by user
daemoneye-cli query "SELECT * FROM processes WHERE user_id = '1000'"

Advanced Queries:

# Process tree analysis
daemoneye-cli query "
SELECT
    p1.pid as parent_pid,
    p1.name as parent_name,
    p2.pid as child_pid,
    p2.name as child_name
FROM processes p1
JOIN processes p2 ON p1.pid = p2.ppid
WHERE p1.name = 'systemd'
"

# Suspicious process patterns
daemoneye-cli query "
SELECT
    pid,
    name,
    executable_path,
    COUNT(*) as occurrence_count
FROM processes
WHERE executable_path LIKE '%temp%'
GROUP BY pid, name, executable_path
HAVING occurrence_count > 5
"

Managing Rules

# List all rules
daemoneye-cli rules list

# Enable/disable rules
daemoneye-cli rules enable rule-name
daemoneye-cli rules disable rule-name

# Validate rule syntax
daemoneye-cli rules validate rule-file.sql

# Test rule execution
daemoneye-cli rules test rule-file.sql

# Import/export rules
daemoneye-cli rules import rules-bundle.tar.gz
daemoneye-cli rules export --output rules-backup.tar.gz

System Health Monitoring

# Check overall health
daemoneye-cli health

# Check component status
daemoneye-cli health --component procmond
daemoneye-cli health --component daemoneye-agent

# View performance metrics
daemoneye-cli metrics

# Check database status
daemoneye-cli database status

# View recent logs
daemoneye-cli logs --tail 50

Troubleshooting

Common Issues

Permission Denied:

# Check if running with sufficient privileges
sudo daemoneye-cli health

# Verify capability requirements
getcap /usr/local/bin/procmond

Database Locked:

# Check for running processes
ps aux | grep daemoneye

# Stop services and restart
sudo systemctl stop daemoneye
sudo systemctl start daemoneye

No Processes Detected:

# Check scan interval
daemoneye-cli config get app.scan_interval_ms

# Verify database path
daemoneye-cli config get database.event_store_path

# Check logs for errors
daemoneye-cli logs --level error

Debug Mode

Enable debug logging for troubleshooting:

app:
  log_level: debug

Or use command-line flag:

daemoneye-agent --config /etc/daemoneye/config.yaml --log-level debug

Getting Help

• Documentation: Check the full documentation in docs/
• Logs: Review logs with daemoneye-cli logs
• Health Checks: Use daemoneye-cli health for system status
• Community: Join discussions on GitHub or community forums

Next Steps

Now that you understand the prerequisites and architecture:

1. Review the Architecture for the system overview
2. Read the Technical Documentation for implementation details
3. Consult the Security section for the threat model and security boundaries
4. See Contributing if you want to build from source

Note: Operator, configuration, and deployment guides will be published with the v1.0.0 release. For the latest project status, see the repository README.

Support

• Documentation: Comprehensive guides in the docs/ directory
• Issues: Report bugs and request features on GitHub
• Community: Join discussions and get help from the community
• Security: Follow responsible disclosure for security issues

Congratulations! You now have DaemonEye running and monitoring your system. The system will continue to collect process data and execute detection rules according to your configuration.

DaemonEye Project Overview

Mission Statement

DaemonEye is a security-focused, high-performance process monitoring system designed to detect suspicious activity on systems through continuous process monitoring, behavioral analysis, and pattern recognition. Its primary purpose is to detect suspicious activity on systems by monitoring abnormal process behavior and patterns.

This is a complete Rust 2024 rewrite of a proven Python prototype, delivering enterprise-grade performance with audit-grade integrity while maintaining the security-first, offline-capable philosophy.

Core Mission

Detect and alert on suspicious system activity through continuous process monitoring, behavioral analysis, and pattern recognition. Provide security operations teams with a reliable, high-performance threat detection solution that operates independently of external dependencies while maintaining audit-grade integrity and operator-centric workflows.

Key Value Propositions

Audit-Grade Integrity

• Certificate Transparency-style Merkle tree with inclusion proofs (In Progress) suitable for compliance and forensics
• BLAKE3 hashing for fast, cryptographically secure hash computation
• Optional Ed25519 signatures for enhanced integrity verification
• Append-only audit ledger with monotonic sequence numbers

Offline-First Operation

• Full functionality without internet access, perfect for airgapped environments
• Local rule caching ensures detection continues during network outages
• Buffered alert delivery with persistent queue for reliability
• Bundle-based configuration and rule distribution system

Security-First Architecture

• Privilege separation with minimal attack surface
• Sandboxed execution and minimal privileges
• Zero unsafe code goal with comprehensive safety verification
• SQL injection prevention with AST validation

High Performance

• <5% CPU overhead while monitoring 10,000+ processes
• Sub-second process enumeration for large systems

• 1,000 records/second database write rate

• <100ms alert latency per detection rule

Operator-Centric Design

• Built for operators, by operators
• Workflows optimized for contested environments
• Comprehensive CLI with multiple output formats
• Color support with NO_COLOR and TERM=dumb handling

Three-Component Architecture

DaemonEye implements a three-component security architecture with strict privilege separation:

1. procmond (Privileged Process Collector)

• Purpose: Minimal privileged component for secure process data collection
• Security: Runs with elevated privileges, drops them immediately after initialization
• Network: No network access whatsoever
• Database: Write-only access to audit ledger
• Features: Process enumeration, executable hashing, Certificate Transparency-style audit ledger

2. daemoneye-agent (Detection Orchestrator)

• Purpose: User-space detection rule execution and alert management
• Security: Minimal privileges, outbound-only network connections
• Database: Read/write access to event store
• Features:
  • SQL-based detection engine with AST validation
  • Multi-channel alerting with reliability guarantees
  • Embedded EventBus broker for collector coordination
  • RPC service for collector lifecycle management (start/stop/restart/health checks)
  • Multi-collector task distribution and result aggregation
  • Correlation tracking for distributed operations

3. daemoneye-cli (Operator Interface)

• Purpose: Command-line interface for queries, management, and diagnostics
• Security: No network access, read-only database operations
• Features: JSON/table output, color handling, shell completions, system health monitoring

4. daemoneye-lib (Shared Core)

• Purpose: Common functionality shared across all components
• Modules: config, models, storage, detection, alerting, crypto, telemetry
• Security: Trait-based abstractions with security boundaries

Target Users

Primary Users

• SOC Analysts: Monitoring fleet infrastructure for process anomalies
• Security Operations & Incident Response Teams: Investigating compromised systems
• System Reliability Engineers: Requiring low-overhead monitoring
• Blue Team Security Engineers: Integrating with existing security infrastructure
• DevSecOps Teams: Embedding security monitoring in deployments

Organizational Context

This repository ships the agent-side Community tier. It is appropriate for individual operators, security researchers, homelabs, and small teams that want sovereign process visibility without a SaaS tether or central server. Larger deployments (centralized fleet management, multi-site aggregation, kernel-level collection) are served by commercial tiers that extend this foundation and are sold separately, not in this repo.

Key Features

Threat Detection Capabilities

Process Behavior Analysis

• Detect process hollowing and executable integrity violations
• Identify suspicious parent-child relationships
• Monitor process lifecycle events in real-time
• Track process memory usage and CPU consumption patterns

Anomaly Detection

• Identify unusual resource consumption patterns
• Detect suspicious process name duplications
• Monitor for process injection techniques
• Track unusual network activity patterns

SQL-Based Detection Engine

• Flexible rule creation using standard SQL queries
• Sandboxed execution with resource limits
• AST validation to prevent injection attacks
• Comprehensive library of built-in detection rules

Built-in Detection Rules

• Common malware tactics, techniques, and procedures (TTPs)
• MITRE ATT&CK framework coverage
• Process hollowing and injection detection
• Suspicious network activity patterns

System Integration

Cross-Platform Support

• Linux: Native process enumeration via sysinfo (procfs access through the sysinfo abstraction; the workspace does not depend on the procfs crate directly)
• macOS: Native process enumeration via sysinfo and platform APIs
• Windows: Native process enumeration via sysinfo and platform APIs

Kernel-level integrations (eBPF on Linux, ETW on Windows, EndpointSecurity on macOS) are provided by commercial-tier collectors, sold separately, not in this repo.

Multi-Channel Alerting

• Local Outputs: stdout, syslog, file output
• Network Outputs: webhooks, email
• SIEM Integration: CEF format for alert forwarding

Certificate Transparency Audit Logging

• Cryptographic integrity for forensic analysis
• Certificate Transparency-style Merkle tree with rs-merkle
• Ed25519 digital signatures and inclusion proofs (In Progress)
• Millisecond-precision timestamps

Resource-Bounded Operation

• Graceful degradation under load
• Memory pressure detection and response
• CPU throttling under high load conditions
• Circuit breaker patterns for external dependencies

Technology Stack

Core Technologies

• Language: Rust 2024 Edition (MSRV: 1.91+)
• Safety: unsafe_code = "forbid" at workspace level with comprehensive linting
• Quality: warnings = "deny" with zero-warnings policy enforced by CI
• Async Runtime: Tokio with full feature set for I/O and task management
• Collection Framework: collector-core for extensible event source management

Database Layer

• Core: redb (pure Rust embedded database) for optimal performance and security
• Features: Concurrent access, ACID transactions, zero-copy deserialization
• Configuration: Separate event store and audit ledger with different durability settings

CLI Framework

• clap v4: Derive macros with shell completions (bash, zsh, fish, PowerShell)
• Terminal: Automatic color detection, NO_COLOR and TERM=dumb support
• Output: JSON and human-readable formats with configurable formatting
• Arguments: Comprehensive argument parsing with validation and help generation

Configuration Management

• Hierarchical loading: Embedded defaults → System files → User files → Environment → CLI flags
• Formats: YAML, JSON, TOML support via figment and config crates
• Validation: Comprehensive validation with detailed error messages

Error Handling

• Libraries: thiserror for structured error types
• Applications: anyhow for error context and chains
• Pattern: Graceful degradation with detailed error context

Logging & Observability

• Structured Logging: tracing ecosystem with JSON output
• Metrics: Optional Prometheus integration
• Performance: Built-in performance monitoring and resource tracking

Performance Requirements

System Performance

• CPU Usage: <5% sustained during continuous monitoring
• Memory Usage: <100MB resident under normal operation
• Process Enumeration: <5 seconds for 10,000+ processes
• Database Operations: >1,000 records/second write rate
• Alert Latency: <100ms per detection rule execution

Scalability

• Single Agent: Monitor 10,000+ processes with minimal overhead

Fleet-level aggregation and federation are commercial-tier concerns, handled outside this repo.

Security Principles

Principle of Least Privilege

• 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

Defense in Depth

• Multiple layers of security controls
• Input validation at all boundaries
• Sandboxed rule execution
• Cryptographic integrity verification

Zero Trust Architecture

• Local IPC over Unix sockets / Windows named pipes with owner-only permissions and CRC32 framing validation
• No inbound network surface; components communicate only over local IPC
• No implicit trust relationships
• Continuous verification and validation

Mutual TLS between host agents and upstream aggregators is a commercial-tier concern, sold separately, not in this repo.

License Model

The DaemonEye components in this repository are licensed under Apache 2.0. Commercial extensions (with their own licensing) ship separately; see evilbitlabs.io for details.

Getting Started

Quick Start

1. Install: Download and install DaemonEye for your platform
2. Configure: Set up basic configuration and detection rules
3. Deploy: Start the monitoring services
4. Monitor: Use the CLI to query data and manage alerts

Next Steps

• Read the Architecture Overview to understand the system design
• Follow the Getting Started Guide for prerequisites and orientation
• Review the Technical Documentation for implementation specifications
• Consult the Security section for the threat model and security boundaries

Note: Operator and configuration guides will be published with the v1.0.0 release.

DaemonEye represents the next generation of process monitoring, combining the security and performance benefits of Rust with proven threat detection techniques to provide a comprehensive solution for modern security operations.

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.

DaemonEye System Architecture

Overview

DaemonEye implements a Rust workspace with six specialized crates (procmond, daemoneye-agent, daemoneye-cli, daemoneye-lib, collector-core, daemoneye-eventbus) that work together following a sophisticated three-component security design around the principle of minimal attack surface while maintaining high performance and audit-grade integrity. The system follows a pipeline processing model where process data flows from collection through detection to alerting, with each component having clearly defined responsibilities and security boundaries.

High-Level Architecture

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

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

        subgraph "daemoneye-cli (Operator Interface)"
            QE[Query Executor]
            HC2[Health Checker]
            DM[Data Manager]
        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]
            CORR[Correlation Metadata]
            TRANS[Cross-Platform Transport]
        end
    end

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

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

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

Component Design

procmond (Privileged Process Collector)

Architectural Role: Minimal privileged component for secure process data collection with purpose-built simplicity.

Core Responsibilities

• Process Enumeration: Cross-platform process data collection using sysinfo crate
• Executable Hashing: SHA-256 hash computation for integrity verification
• Audit Logging: Tamper-evident logging with cryptographic chains
• IPC Communication: Simple protobuf-based communication with daemoneye-agent

Security Boundaries

• Privilege Management: Starts with minimal privileges, optionally requests enhanced access
• Privilege Dropping: Drops all elevated privileges immediately after initialization
• Network Isolation: No network access whatsoever
• Code Simplicity: No SQL parsing or complex query logic
• Audit Logging: Write-only access to hash-chained audit ledger
• Communication: Simple protobuf IPC only (Unix sockets/named pipes)

Key Interfaces

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

#[async_trait]
pub trait HashComputer: Send + Sync {
    async fn compute_hash(&self, path: &Path) -> Result<Option<String>>;
    fn get_algorithm(&self) -> &'static str;
}

#[async_trait]
pub trait AuditLogger: Send + Sync {
    async fn log_event(&self, event: &AuditEvent) -> Result<()>;
    async fn verify_chain(&self) -> Result<ChainVerificationResult>;
}

Implementation Structure

pub struct ProcessCollector {
    config: CollectorConfig,
    hash_computer: Box<dyn HashComputer>,
    audit_logger: Box<dyn AuditLogger>,
    ipc_server: Box<dyn IpcServer>,
    privilege_manager: PrivilegeManager,
}

impl ProcessCollector {
    pub async fn new(config: CollectorConfig) -> Result<Self> {
        let mut privilege_manager = PrivilegeManager::new();

        // Request minimal required privileges
        privilege_manager.request_enhanced_privileges().await?;

        let collector = Self {
            config,
            hash_computer: Box::new(Sha256HashComputer::new()),
            audit_logger: Box::new(HashChainAuditLogger::new(&config.audit_path)?),
            ipc_server: Box::new(UnixSocketServer::new(&config.ipc_path)?),
            privilege_manager,
        };

        // Drop privileges immediately after initialization
        collector.privilege_manager.drop_privileges().await?;

        Ok(collector)
    }
}

daemoneye-agent (Detection Orchestrator)

Architectural Role: User-space detection rule execution, alert management, and procmond lifecycle management.

Core 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

• User Space Operation: Operates in user space with minimal privileges
• Event Store Management: Manages redb event store (read/write access)
• Rule Translation: Translates complex SQL rules into simple protobuf tasks for procmond
• Network Access: Outbound-only network connections for alert delivery
• Sandboxed Execution: Sandboxed rule execution with resource limits
• IPC Communication: IPC client for communication with procmond

Key Interfaces

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

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

#[async_trait]
pub trait ProcessManager: Send + Sync {
    async fn start_procmond(&self) -> Result<()>;
    async fn stop_procmond(&self) -> Result<()>;
    async fn restart_procmond(&self) -> Result<()>;
    async fn health_check(&self) -> Result<HealthStatus>;
}

Implementation Structure

Validated/derived SQL does not execute directly against redb; redb is a key/value store with no SQL, prepare, or bind API. Per ADR-0006, the engine runs derived standard SQL through an Apache DataFusion SessionContext whose catalog is populated by per-domain redb-backed TableProvider implementations. The custom detection dialect is lowered at rule-compile time into (a) protobuf collection tasks and (b) derived standard SQL; the runtime executor only ever sees the derived SQL. The full pipeline (validation, predicate pushdown, schema catalog, execution, and degradation semantics) is specified in .kiro/specs/daemoneye-core-monitoring/design.md.

pub struct DetectionEngine {
    // DataFusion session executing validated/derived SQL; redb per-domain
    // tables are exposed through TableProvider implementations (ADR-0006).
    query_ctx: datafusion::execution::context::SessionContext,
    table_providers: Vec<Arc<dyn datafusion::datasource::TableProvider>>,
    rule_manager: RuleManager,
    alert_manager: AlertManager,
    sql_validator: SqlValidator,
    ipc_client: IpcClient,
    process_manager: ProcessManager,
}

impl DetectionEngine {
    pub async fn new(config: AgentConfig) -> Result<Self> {
        // Build a locked-down DataFusion session and register redb-backed
        // TableProviders for each collector domain (process, etc.).
        let (query_ctx, table_providers) =
            build_session_context(&config.event_store_path, ALLOWED_SQL_FUNCTIONS)?;

        // Initialize SQL validator with security constraints
        let sql_validator = SqlValidator::new()
            .with_allowed_functions(ALLOWED_SQL_FUNCTIONS)
            .with_read_only_mode(true)
            .with_timeout(Duration::from_secs(30));

        // Initialize IPC client for procmond communication
        let ipc_client = IpcClient::new(&config.procmond_socket_path)?;

        // Start procmond process
        let process_manager = ProcessManager::new(config.procmond_config);
        process_manager.start_procmond().await?;

        Ok(Self {
            query_ctx,
            table_providers,
            rule_manager: RuleManager::new(&config.rules_path)?,
            alert_manager: AlertManager::new(&config.alerting_config)?,
            sql_validator,
            ipc_client,
            process_manager,
        })
    }
}

daemoneye-cli (Operator Interface)

Architectural Role: Command-line interface for queries, management, and diagnostics.

Core 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 network access whatsoever
• No Direct Event Store Access: Communicates through daemoneye-agent
• Input Validation: Comprehensive validation for all user-provided data
• Safe SQL Execution: SQL execution via daemoneye-agent with prepared statements
• Local Communication Only: Communicates only with daemoneye-agent

Key Interfaces

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

#[async_trait]
pub trait HealthChecker: Send + Sync {
    async fn check_system_health(&self) -> Result<HealthStatus>;
    async fn check_component_health(&self, component: Component) -> Result<ComponentHealth>;
}

#[async_trait]
pub trait DataManager: Send + Sync {
    async fn export_alerts(
        &self,
        format: ExportFormat,
        filter: &AlertFilter,
    ) -> Result<ExportResult>;
    async fn export_processes(
        &self,
        format: ExportFormat,
        filter: &ProcessFilter,
    ) -> Result<ExportResult>;
}

daemoneye-lib (Shared Core)

Architectural Role: Common functionality shared across all components.

Core Modules

• config: Hierarchical configuration management with validation
• models: Core data structures and serialization/deserialization
• storage: Event store abstractions and connection management
• detection: SQL validation and rule execution framework
• alerting: Multi-channel alert delivery system
• crypto: Cryptographic functions for audit chains and integrity
• telemetry: Observability, metrics collection, and health monitoring

Module Structure

pub mod config {
    pub mod environment;
    pub mod hierarchical;
    pub mod validation;
}

pub mod models {
    pub mod alert;
    pub mod audit;
    pub mod detection_rule;
    pub mod process;
}

pub mod storage {
    pub mod audit_ledger;
    pub mod connection_pool;
    pub mod redb;
}

pub mod detection {
    pub mod rule_engine;
    pub mod sandbox;
    pub mod sql_validator;
}

pub mod alerting {
    pub mod deduplication;
    pub mod delivery;
    pub mod sinks;
}

pub mod crypto {
    pub mod hash_chain;
    pub mod integrity;
    pub mod signatures;
}

pub mod telemetry {
    pub mod health;
    pub mod metrics;
    pub mod tracing;
}

Data Flow Architecture

Process Collection Pipeline

sequenceDiagram
    participant SA as daemoneye-agent
    participant PM as procmond
    participant SYS as System
    participant AL as Audit Ledger

    SA->>PM: DetectionTask(ENUMERATE_PROCESSES)
    PM->>SYS: Enumerate processes
    SYS-->>PM: Process data
    PM->>PM: Compute SHA-256 hashes
    PM->>AL: Write to audit ledger
    PM-->>SA: DetectionResult(processes)
    SA->>SA: Store in event store

Detection and Alerting Pipeline

sequenceDiagram
    participant DE as Detection Engine
    participant DB as Event Store
    participant RM as Rule Manager
    participant AM as Alert Manager
    participant SINK as Alert Sinks

    DE->>RM: Load detection rules
    RM-->>DE: SQL rules
    DE->>DB: Execute SQL queries
    DB-->>DE: Query results
    DE->>AM: Generate alerts
    AM->>AM: Deduplicate alerts
    AM->>SINK: Deliver alerts (parallel)
    SINK-->>AM: Delivery results

Query and Management Pipeline

sequenceDiagram
    participant CLI as daemoneye-cli
    participant SA as daemoneye-agent
    participant DB as Event Store

    CLI->>SA: Execute query request
    SA->>SA: Validate SQL query
    SA->>DB: Execute prepared statement
    DB-->>SA: Query results
    SA->>SA: Format results
    SA-->>CLI: Formatted results

Communication Architecture

DaemonEye uses a dual-protocol architecture for different communication needs:

1. IPC Protocol: Direct protobuf communication between daemoneye-cli and daemoneye-agent
2. EventBus Protocol: Local IPC pub/sub messaging between collectors and agent on the same system

EventBus Architecture

The daemoneye-eventbus provides local cross-platform pub/sub messaging for collector coordination on a single system with the following features:

Topic Hierarchy

The event bus uses a hierarchical topic structure with up to 4 levels:

Event Topics (Data Flow):

• events.process.* - Process monitoring events (lifecycle, metadata, tree, integrity, anomaly, batch)
• events.network.* - Network events (future extension)
• events.filesystem.* - Filesystem events (future extension)
• events.performance.* - Performance events (future extension)

Control Topics (Management Flow):

• control.collector.* - Collector lifecycle and configuration
• control.agent.* - Agent orchestration and policy
• control.health.* - Health monitoring and diagnostics

Wildcard Support

• Single-level wildcard (+): Matches exactly one segment
  • Example: events.+.lifecycle matches events.process.lifecycle
• Multi-level wildcard (#): Matches zero or more segments
  • Example: events.process.# matches all process events

Correlation Metadata

The event bus supports comprehensive correlation tracking for multi-collector workflows:

// Hierarchical correlation tracking
let parent_metadata = CorrelationMetadata::new("workflow-id".to_string())
    .with_stage("detection".to_string())
    .with_tag("workflow".to_string(), "threat_analysis".to_string());

let child_metadata = parent_metadata.create_child("analysis-id".to_string());
// Child inherits workflow stage and tags from parent

Use Cases:

• Multi-collector workflows on the same system (process → network → filesystem analysis)
• Forensic investigation tracking across local collectors
• Local workflow tracing with correlation IDs
• Performance analysis across workflow stages within a single host

Access Control

Topics have three access levels:

• Public: Accessible to all components (e.g., control.health.*)
• Restricted: Component-specific access (e.g., events.process.* for procmond)
• Privileged: Requires authentication (e.g., control.collector.lifecycle)

Embedded Broker

The daemoneye-agent runs an embedded EventBus broker that:

• Manages topic subscriptions and message routing
• Enforces access control policies
• Tracks correlation metadata for workflow coordination
• Provides statistics and health monitoring

For complete EventBus documentation, see the daemoneye-eventbus crate documentation.

IPC Protocol Design

Protocol Specification

The IPC protocol uses Protocol Buffers for efficient, type-safe communication between daemoneye-cli and daemoneye-agent.

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;
}

message ProcessFilter {
    repeated string process_names = 1;
    repeated uint32 pids = 2;
    optional string executable_pattern = 3;
}

message HashCheck {
    string expected_hash = 1;
    string hash_algorithm = 2;
    string executable_path = 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;
}

message ProcessRecord {
    uint32 pid = 1;
    optional uint32 ppid = 2;
    string name = 3;
    optional string executable_path = 4;
    repeated string command_line = 5;
    optional int64 start_time = 6;
    optional double cpu_usage = 7;
    optional uint64 memory_usage = 8;
    optional string executable_hash = 9;
    optional string hash_algorithm = 10;
    optional string user_id = 11;
    bool accessible = 12;
    bool file_exists = 13;
    int64 collection_time = 14;
}

Transport Layer

Unix Domain Sockets (Linux/macOS):

pub struct UnixSocketServer {
    path: PathBuf,
    listener: UnixListener,
}

impl IpcServer for UnixSocketServer {
    async fn serve<F>(&self, handler: F) -> Result<()>
    where
        F: Fn(DetectionTask) -> Result<DetectionResult> + Send + Sync + 'static,
    {
        let mut incoming = self.listener.incoming();

        while let Some(stream) = incoming.next().await {
            let stream = stream?;
            let handler = handler.clone();

            tokio::spawn(async move {
                Self::handle_connection(stream, handler).await;
            });
        }

        Ok(())
    }
}

Named Pipes (Windows):

pub struct NamedPipeServer {
    pipe_name: String,
    server: NamedPipeServerStream,
}

impl IpcServer for NamedPipeServer {
    async fn serve<F>(&self, handler: F) -> Result<()>
    where
        F: Fn(DetectionTask) -> Result<DetectionResult> + Send + Sync + 'static,
    {
        // Windows named pipe implementation
        // Similar to Unix socket but using Windows named pipes
    }
}

Data Storage Architecture

Event Store (redb)

Purpose: High-performance process data storage with concurrent access.

Schema Design:

// Process snapshots table
pub struct ProcessSnapshot {
    pub id: Uuid,
    pub scan_id: i64,
    pub collection_time: i64,
    pub pid: u32,
    pub ppid: Option<u32>,
    pub name: String,
    pub executable_path: Option<PathBuf>,
    pub command_line: Vec<String>,
    pub start_time: Option<i64>,
    pub cpu_usage: Option<f64>,
    pub memory_usage: Option<u64>,
    pub executable_hash: Option<String>,
    pub hash_algorithm: Option<String>,
    pub user_id: Option<String>,
    pub accessible: bool,
    pub file_exists: bool,
    pub platform_data: Option<serde_json::Value>,
}

// Scan metadata table
pub struct ScanMetadata {
    pub id: i64,
    pub start_time: i64,
    pub end_time: i64,
    pub process_count: i32,
    pub collection_duration_ms: i64,
    pub system_info: SystemInfo,
}

// Detection rules table
pub struct DetectionRule {
    pub id: String,
    pub name: String,
    pub description: Option<String>,
    pub version: i32,
    pub sql_query: String,
    pub enabled: bool,
    pub severity: AlertSeverity,
    pub category: Option<String>,
    pub tags: Vec<String>,
    pub author: Option<String>,
    pub created_at: i64,
    pub updated_at: i64,
    pub source_type: RuleSourceType,
    pub source_path: Option<PathBuf>,
}

// Alerts table
pub struct Alert {
    pub id: Uuid,
    pub alert_time: i64,
    pub rule_id: String,
    pub title: String,
    pub description: String,
    pub severity: AlertSeverity,
    pub scan_id: Option<i64>,
    pub affected_processes: Vec<u32>,
    pub process_count: i32,
    pub alert_data: serde_json::Value,
    pub rule_execution_time_ms: Option<i64>,
    pub dedupe_key: String,
}

Audit Ledger (Hash-chained)

Purpose: Tamper-evident audit trail with cryptographic integrity using hash-chained log file.

Implementation:

The audit ledger is implemented as a hash-chained log file, not a database table. Each entry contains a cryptographic hash of the previous entry, creating an immutable chain.

Hash Chain Implementation:

pub struct AuditChain {
    hasher: blake3::Hasher,
    signer: Option<ed25519_dalek::Keypair>,
    previous_hash: Option<blake3::Hash>,
}

impl AuditChain {
    pub fn append_entry(&mut self, entry: &AuditEntry) -> Result<AuditRecord> {
        let entry_data = serde_json::to_vec(entry)?;
        let entry_hash = blake3::hash(&entry_data);

        let record = AuditRecord {
            sequence: self.next_sequence(),
            timestamp: SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis() as i64,
            actor: entry.actor.clone(),
            action: entry.action.clone(),
            payload_hash: entry_hash,
            previous_hash: self.previous_hash,
            entry_hash: self.compute_entry_hash(&entry_hash)?,
            signature: self.sign_entry(&entry_hash)?,
        };

        self.previous_hash = Some(record.entry_hash);
        Ok(record)
    }

    pub fn verify_chain(&self, records: &[AuditRecord]) -> Result<VerificationResult> {
        // Verify hash chain integrity and signatures
        for (i, record) in records.iter().enumerate() {
            if i > 0 {
                let prev_record = &records[i - 1];
                if record.previous_hash != Some(prev_record.entry_hash) {
                    return Err(VerificationError::ChainBroken(i));
                }
            }

            // Verify entry hash
            let computed_hash = self.compute_entry_hash(&record.payload_hash)?;
            if record.entry_hash != computed_hash {
                return Err(VerificationError::HashMismatch(i));
            }

            // Verify signature if present
            if let Some(signature) = &record.signature {
                self.verify_signature(&record.payload_hash, signature)?;
            }
        }

        Ok(VerificationResult::Valid)
    }
}

Security Architecture

Privilege Separation Model

Principle: Each component operates with the minimum privileges required for its function.

pub struct PrivilegeManager {
    initial_privileges: Privileges,
    current_privileges: Privileges,
    drop_completed: bool,
}

impl PrivilegeManager {
    pub async fn request_enhanced_privileges(&mut self) -> Result<()> {
        // Platform-specific privilege escalation
        #[cfg(target_os = "linux")]
        self.request_linux_capabilities()?;

        #[cfg(target_os = "windows")]
        self.request_windows_privileges()?;

        #[cfg(target_os = "macos")]
        self.request_macos_entitlements()?;

        Ok(())
    }

    pub async fn drop_privileges(&mut self) -> Result<()> {
        // Immediate privilege drop after initialization
        self.drop_all_elevated_privileges()?;
        self.drop_completed = true;
        self.audit_privilege_drop().await?;
        Ok(())
    }
}

SQL Injection Prevention

AST Validation: All user-provided SQL undergoes comprehensive validation.

pub struct SqlValidator {
    parser: sqlparser::Parser<sqlparser::dialect::SQLiteDialect>,
    allowed_functions: HashSet<String>,
}

impl SqlValidator {
    pub fn validate_query(&self, sql: &str) -> Result<ValidationResult> {
        let ast = self.parser.parse_sql(sql)?;

        for statement in &ast {
            match statement {
                Statement::Query(query) => self.validate_select_query(query)?,
                _ => return Err(ValidationError::ForbiddenStatement),
            }
        }

        Ok(ValidationResult::Valid)
    }

    fn validate_select_query(&self, query: &Query) -> Result<()> {
        // Validate SELECT body, WHERE clauses, functions, etc.
        // Reject any non-whitelisted constructs
        self.validate_select_body(&query.body)?;
        self.validate_where_clause(&query.selection)?;
        Ok(())
    }
}

Resource Management

Bounded Channels: Configurable capacity with backpressure policies.

pub struct BoundedChannel<T> {
    sender: mpsc::Sender<T>,
    receiver: mpsc::Receiver<T>,
    capacity: usize,
    backpressure_policy: BackpressurePolicy,
}

impl<T> BoundedChannel<T> {
    pub async fn send(&self, item: T) -> Result<(), ChannelError> {
        match self.backpressure_policy {
            BackpressurePolicy::Block => {
                self.sender.send(item).await?;
            }
            BackpressurePolicy::Drop => {
                if self.sender.try_send(item).is_err() {
                    return Err(ChannelError::ChannelFull);
                }
            }
            BackpressurePolicy::Error => {
                self.sender.try_send(item)?;
            }
        }
        Ok(())
    }
}

Performance Characteristics

Process Collection Performance

• 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 Performance

• 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 Performance

• 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

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

Collector-Core Framework

The collector-core framework provides a unified collection infrastructure that enables multiple monitoring components while maintaining shared operational foundation.

Table of Contents

• Overview
• Architecture
• Core Components
  • EventSource Trait
  • Capability System
  • Collection Events
  • Collector Runtime
• Event Processing Pipeline
  • Event Flow
  • Batching and Backpressure
• Configuration System
  • Hierarchical Configuration
  • Configuration Structure
• Health Monitoring
  • Health Check System
  • Health Status Types
• IPC Integration
  • Collector IPC Server
  • Protocol Support
• Event Source Implementation
  • Process Event Source Example
• Advanced Features
  • Analysis Chain Coordination
  • Trigger Management
  • Event Bus System
• Performance Characteristics
  • Throughput Targets
  • Scalability
• Testing Strategy
  • Test Coverage
  • Test Utilities
• Usage Examples
  • Basic Collector Setup
  • Custom Event Source
• Best Practices
  • Event Source Development
  • Configuration Management
  • Performance Optimization

Overview

The collector-core framework is the foundation of DaemonEye’s extensible monitoring architecture. It provides:

• Universal EventSource trait for pluggable collection implementations
• Collector runtime for event source management and aggregation
• Extensible CollectionEvent enum for unified event handling
• Capability negotiation through SourceCaps bitflags
• Shared infrastructure for configuration, logging, and health checks

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Collector Runtime                        │
├─────────────────────────────────────────────────────────────┤
│  EventSource    EventSource    EventSource    EventSource   │
│  (Process)      (Network)      (Filesystem)   (Performance) │
└─────────────────────────────────────────────────────────────┘

The framework separates collection methodology from operational infrastructure, allowing different collection strategies to share the same runtime foundation.

Core Components

EventSource Trait

The EventSource trait abstracts collection methodology from operational infrastructure:

#[async_trait]
pub trait EventSource: Send + Sync {
    fn name(&self) -> &'static str;
    fn capabilities(&self) -> SourceCaps;

    async fn start(
        &self,
        tx: mpsc::Sender<CollectionEvent>,
        shutdown_signal: Arc<AtomicBool>,
    ) -> anyhow::Result<()>;

    async fn stop(&self) -> anyhow::Result<()>;
    async fn health_check(&self) -> anyhow::Result<()>;
}

Capability System

The SourceCaps bitflags enable capability negotiation between components:

bitflags! {
    pub struct SourceCaps: u32 {
        const PROCESS = 1 << 0;        // Process monitoring
        const NETWORK = 1 << 1;        // Network monitoring
        const FILESYSTEM = 1 << 2;     // Filesystem monitoring
        const PERFORMANCE = 1 << 3;    // Performance monitoring
        const REALTIME = 1 << 4;       // Real-time event streaming
        const KERNEL_LEVEL = 1 << 5;   // Kernel-level access
        const SYSTEM_WIDE = 1 << 6;    // System-wide monitoring
    }
}

Collection Events

The CollectionEvent enum provides unified event handling:

pub enum CollectionEvent {
    Process(ProcessEvent),
    Network(NetworkEvent),
    Filesystem(FilesystemEvent),
    Performance(PerformanceEvent),
    TriggerRequest(TriggerRequest),
}

Collector Runtime

The Collector provides unified runtime for multiple event sources:

pub struct Collector {
    config: CollectorConfig,
    sources: Vec<Box<dyn EventSource>>,
}

impl Collector {
    pub fn new(config: CollectorConfig) -> Self;
    pub fn register(&mut self, source: Box<dyn EventSource>) -> anyhow::Result<()>;
    pub fn capabilities(&self) -> SourceCaps;
    pub async fn run(self) -> Result<()>;
}

Event Processing Pipeline

Event Flow

1. Event Sources generate events based on their collection methodology
2. Event Channel receives events via mpsc::Sender<CollectionEvent>
3. Event Processor handles batching, backpressure, and processing
4. Event Bus (optional) provides pub/sub event distribution
5. Storage/Forwarding processes events according to configuration

Batching and Backpressure

The framework includes sophisticated event processing with:

• Configurable Batching: Events are batched for efficient processing
• Backpressure Handling: Semaphore-based flow control prevents memory exhaustion
• Timeout Management: Batch timeouts ensure timely processing
• Graceful Degradation: System continues operation under load

// Batch configuration
fn create_batch_config() -> CollectorConfig {
    CollectorConfig::new()
        .with_max_batch_size(1000)
        .with_batch_timeout(Duration::from_secs(5))
        .with_backpressure_threshold(800)
}

Configuration System

Hierarchical Configuration

The framework supports hierarchical configuration loading:

1. Command-line flags (highest precedence)
2. Environment variables
3. User configuration files
4. System configuration files
5. Embedded defaults (lowest precedence)

Configuration Structure

pub struct CollectorConfig {
    pub component_name: String,
    pub max_event_sources: usize,
    pub event_buffer_size: usize,
    pub max_batch_size: usize,
    pub batch_timeout: Duration,
    pub shutdown_timeout: Duration,
    pub health_check_interval: Duration,
    pub enable_telemetry: bool,
    pub enable_debug_logging: bool,
    // ... additional configuration options
}

Health Monitoring

Health Check System

The framework provides comprehensive health monitoring:

• Source Health Checks: Individual event source health monitoring
• System Resource Monitoring: CPU, memory, and performance tracking
• Error Rate Monitoring: Automatic error rate calculation and alerting
• Telemetry Collection: Performance metrics and operational statistics

Health Status Types

pub enum HealthStatus {
    Healthy,
    Degraded,
    Unhealthy,
}

IPC Integration

Collector IPC Server

The framework includes IPC server capabilities for external communication:

pub struct CollectorIpcServer {
    // IPC server implementation
}

impl CollectorIpcServer {
    pub async fn start(&mut self) -> Result<()>;
    pub async fn handle_request(&self, request: IpcRequest) -> IpcResponse;
    pub fn get_capabilities(&self) -> SourceCaps;
}

Protocol Support

• Unix Domain Sockets (Linux/macOS)
• Named Pipes (Windows)
• Protobuf Serialization for efficient communication
• Automatic Reconnection with exponential backoff

Event Source Implementation

Process Event Source Example

use async_trait::async_trait;
use collector_core::{CollectionEvent, EventSource, ProcessEvent, SourceCaps};

pub struct ProcessEventSource {
    config: ProcessSourceConfig,
    db_manager: Arc<Mutex<DatabaseManager>>,
}

#[async_trait]
impl EventSource for ProcessEventSource {
    fn name(&self) -> &'static str {
        "process-collector"
    }

    fn capabilities(&self) -> SourceCaps {
        SourceCaps::PROCESS | SourceCaps::REALTIME | SourceCaps::SYSTEM_WIDE
    }

    async fn start(
        &self,
        tx: mpsc::Sender<CollectionEvent>,
        shutdown_signal: Arc<AtomicBool>,
    ) -> anyhow::Result<()> {
        let mut interval = tokio::time::interval(self.config.collection_interval);

        while !shutdown_signal.load(Ordering::Relaxed) {
            interval.tick().await;

            // Collect process information
            let processes = self.collect_processes().await?;

            // Send events
            for process in processes {
                let event = CollectionEvent::Process(ProcessEvent {
                    pid: process.pid,
                    name: process.name,
                    timestamp: SystemTime::now(),
                    // ... additional fields
                });

                if tx.send(event).await.is_err() {
                    warn!("Event channel closed, stopping collection");
                    break;
                }
            }
        }

        Ok(())
    }

    async fn stop(&self) -> anyhow::Result<()> {
        // Cleanup resources
        Ok(())
    }
}

Advanced Features

Analysis Chain Coordination

The framework includes analysis chain coordination for complex workflows:

pub struct AnalysisChainCoordinator {
    // Coordinates multi-stage analysis workflows
}

pub struct AnalysisWorkflowDefinition {
    pub stages: Vec<AnalysisStage>,
    pub dependencies: HashMap<String, Vec<String>>,
    pub timeout: Duration,
}

Trigger Management

Sophisticated trigger management for event-driven analysis:

pub struct TriggerManager {
    // Manages trigger conditions and priorities
}

pub struct TriggerCondition {
    pub sql_condition: String,
    pub priority: TriggerPriority,
    pub resource_limits: TriggerResourceLimits,
}

Event Bus System

Optional pub/sub event distribution:

pub struct EventBus {
    // Pub/sub event distribution system
}

pub struct EventSubscription {
    pub filter: EventFilter,
    pub correlation_filter: Option<CorrelationFilter>,
    pub subscriber_id: String,
}

Performance Characteristics

Throughput Targets

• Event Processing: >1,000 events/second
• CPU Overhead: <5% sustained usage
• Memory Usage: <100MB resident under normal operation
• Latency: <100ms per event processing

Scalability

• Event Sources: Support for 16+ concurrent event sources
• Event Buffer: Configurable buffer sizes (1,000-10,000 events)
• Batch Processing: Configurable batch sizes (100-1,000 events)
• Backpressure: Automatic flow control and graceful degradation

Testing Strategy

Test Coverage

The framework includes comprehensive testing:

• Unit Tests: Individual component functionality
• Integration Tests: Cross-component interaction
• Performance Tests: Throughput and latency benchmarks
• Property Tests: Generative testing for edge cases

Test Utilities

// Test utilities for event source testing
pub mod test_utils {
    pub struct MockEventSource;
    pub struct TestCollector;
    pub fn create_test_config() -> CollectorConfig;
}

Usage Examples

Basic Collector Setup

use collector_core::{Collector, CollectorConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = CollectorConfig::new()
        .with_component_name("my-collector".to_string())
        .with_max_event_sources(4)
        .with_event_buffer_size(2000);

    let mut collector = Collector::new(config);

    // Register event sources
    collector.register(Box::new(ProcessEventSource::new()))?;
    collector.register(Box::new(NetworkEventSource::new()))?;

    // Run the collector
    collector.run().await
}

Custom Event Source

use async_trait::async_trait;
use collector_core::{CollectionEvent, EventSource, SourceCaps};

struct CustomEventSource;

#[async_trait]
impl EventSource for CustomEventSource {
    fn name(&self) -> &'static str {
        "custom-source"
    }

    fn capabilities(&self) -> SourceCaps {
        SourceCaps::PERFORMANCE | SourceCaps::REALTIME
    }

    async fn start(
        &self,
        tx: mpsc::Sender<CollectionEvent>,
        shutdown_signal: Arc<AtomicBool>,
    ) -> anyhow::Result<()> {
        // Custom collection logic
        Ok(())
    }

    async fn stop(&self) -> anyhow::Result<()> {
        Ok(())
    }
}

Best Practices

Event Source Development

1. Implement Graceful Shutdown: Always check the shutdown signal
2. Handle Errors Gracefully: Continue operation when possible
3. Use Structured Logging: Provide detailed operational information
4. Monitor Performance: Track collection rates and resource usage
5. Test Thoroughly: Include unit, integration, and performance tests

Configuration Management

1. Use Builder Pattern: Provide fluent configuration APIs
2. Validate Configuration: Check configuration at startup
3. Support Hierarchical Loading: Allow multiple configuration sources
4. Document Defaults: Clearly document default values
5. Environment Variable Support: Enable container-friendly configuration

Performance Optimization

1. Batch Events: Use batching for efficient processing
2. Monitor Backpressure: Implement flow control mechanisms
3. Optimize Hot Paths: Profile and optimize critical code paths
4. Use Async I/O: Leverage Tokio for concurrent operations
5. Resource Limits: Implement resource budgets and limits

The collector-core framework provides the foundation for DaemonEye’s extensible monitoring architecture, enabling multiple collection strategies while maintaining shared operational infrastructure.

Technical Documentation

This section contains comprehensive technical documentation for DaemonEye, covering implementation details, architecture specifications, and technical guides.

Table of Contents

• Core Monitoring
• Platform-Specific Process Collectors
  • Windows Process Collector
  • macOS Process Collector
• Technical Architecture
  • Component Overview
  • Data Flow
  • Technology Stack
• Implementation Details
  • Process Collection
  • Event Store Operations
  • Alert System
• Performance Considerations
  • Memory Management
  • CPU Usage
  • Storage Requirements
• Security Implementation
  • Input Validation
  • SQL Injection Prevention
  • Cryptographic Integrity
• Testing Strategy
  • Unit Testing
  • Integration Testing
  • Performance Testing
• Deployment Considerations
  • Container Deployment
  • Platform Support
  • Configuration Management

Core Monitoring

The core monitoring system provides real-time process monitoring and threat detection capabilities. This is the foundation of DaemonEye and is available in all tiers.

Read Core Monitoring Documentation →

Platform-Specific Process Collectors

DaemonEye provides platform-specific process collectors that leverage native operating system capabilities for enhanced monitoring and security analysis.

Windows Process Collector

The Windows process collector provides comprehensive Windows-specific capabilities including SeDebugPrivilege detection, process tokens, UAC elevation status, and Windows service monitoring.

Read Windows Process Collector Documentation →

macOS Process Collector

The macOS process collector provides comprehensive macOS-specific capabilities including kernel extension integration, process code signing verification, system integrity protection monitoring, and EndpointSecurity framework integration.

Read macOS Process Collector Documentation →

Technical Architecture

Component Overview

DaemonEye follows a three-component security architecture:

1. ProcMonD: Privileged process monitoring daemon
2. daemoneye-agent: User-space orchestrator and alerting
3. daemoneye-cli: Command-line interface and management

Data Flow

graph LR
    A[<b>ProcMonD</b><br/>• Process Enum<br/>• Hashing<br/>• Audit] -->|Process Data<br/>Alerts| B[<b>daemoneye-agent</b><br/>• Alerting<br/>• Rules<br/>• Network<br/>• Storage]
    B -->|Lifecycle Mgmt<br/>Tasking| A
    B -->|Query Results<br/>Status| C[<b>daemoneye-cli</b><br/>• Queries<br/>• Config<br/>• Monitor<br/>• Manage]
    C -->|Commands<br/>Config| B

Technology Stack

• Language: Rust 2024 Edition
• Runtime: Tokio async runtime
• Event Store: redb (pure Rust embedded database)
• Audit Ledger: Certificate Transparency-style Merkle tree
• IPC: Custom Protobuf over Unix Sockets
• CLI: clap v4 with derive macros
• Configuration: figment with hierarchical loading
• Logging: tracing ecosystem with structured JSON
• Testing: cargo-nextest with comprehensive test suite

Implementation Details

Process Collection

The process collection system uses the sysinfo crate for cross-platform process enumeration:

use sysinfo::System;

pub struct ProcessCollector {
    system: System,
}

impl ProcessCollector {
    pub fn new() -> Self {
        Self {
            system: System::new_all(),
        }
    }

    pub async fn collect_processes(&mut self) -> Result<Vec<ProcessInfo>, CollectionError> {
        self.system.refresh_all();

        let processes = self
            .system
            .processes()
            .values()
            .map(|p| ProcessInfo::from(p))
            .collect();

        Ok(processes)
    }
}

Event Store Operations

DaemonEye uses redb for high-performance event storage:

use redb::{Database, ReadableTable, WritableTable};

pub struct EventStore {
    db: Database,
}

impl EventStore {
    pub fn new(path: &str) -> Result<Self, redb::Error> {
        let db = Database::create(path)?;
        Ok(Self { db })
    }

    pub async fn insert_process(&self, process: &ProcessInfo) -> Result<(), redb::Error> {
        let write_txn = self.db.begin_write()?;
        {
            let mut table = write_txn.open_table(PROCESS_TABLE)?;
            let key = process.pid;
            let value = serde_json::to_vec(process)?;
            table.insert(key, &value)?;
        }
        write_txn.commit()?;
        Ok(())
    }
}

Alert System

The alert system provides multi-channel alert delivery:

use async_trait::async_trait;

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

pub struct AlertManager {
    sinks: Vec<Box<dyn AlertSink>>,
}

impl AlertManager {
    pub async fn send_alert(&self, alert: Alert) -> Result<(), AlertError> {
        let mut results = Vec::new();

        for sink in &self.sinks {
            let result = sink.send(&alert).await;
            results.push(result);
        }

        // Check if any sink succeeded
        if results.iter().any(|r| r.is_ok()) {
            Ok(())
        } else {
            Err(AlertError::DeliveryFailed)
        }
    }
}

Performance Considerations

Memory Management

DaemonEye is designed for minimal memory usage:

• Process Collection: ~1MB per 1000 processes
• Database Operations: ~10MB for 100,000 records
• Alert Processing: ~1MB for 10,000 alerts
• Total Memory: <100MB under normal operation

CPU Usage

CPU usage is optimized for minimal impact:

• Process Collection: <5% CPU sustained
• Database Operations: <2% CPU for queries
• Alert Processing: <1% CPU for delivery
• Total CPU: <5% sustained during monitoring

Storage Requirements

Storage requirements scale with data retention:

• Process Records: ~1KB per process per collection
• Alert Records: ~500B per alert
• Audit Logs: ~100B per operation
• Total Storage: ~1GB per month for 1000 processes

Security Implementation

Input Validation

All inputs are validated using the validator crate:

use validator::{Validate, ValidationError};

#[derive(Validate)]
pub struct DetectionRule {
    #[validate(length(min = 1, max = 1000))]
    pub name: String,

    #[validate(custom = "validate_sql")]
    pub sql_query: String,

    #[validate(range(min = 1, max = 1000))]
    pub priority: u32,
}

fn validate_sql(sql: &str) -> Result<(), ValidationError> {
    // Parse and validate SQL syntax
    let ast = sqlparser::parse(sql)?;
    validate_ast(&ast)?;
    Ok(())
}

SQL Injection Prevention

Multiple layers of SQL injection prevention:

1. AST Validation: Parse and validate SQL queries
2. Prepared Statements: Use parameterized queries
3. Sandboxed Execution: Isolated query execution
4. Input Sanitization: Clean and validate all inputs

Cryptographic Integrity

BLAKE3 hashing and Ed25519 signatures ensure data integrity:

use blake3::Hasher;
use ed25519_dalek::{Keypair, Signature};

pub struct IntegrityChecker {
    hasher: Hasher,
    keypair: Keypair,
}

impl IntegrityChecker {
    pub fn hash_data(&self, data: &[u8]) -> [u8; 32] {
        self.hasher.update(data).finalize().into()
    }

    pub fn sign_data(&self, data: &[u8]) -> Signature {
        self.keypair.sign(data)
    }
}

Testing Strategy

Unit Testing

Comprehensive unit testing with mocks and test doubles:

#[cfg(test)]
mod tests {
    use super::*;
    use mockall::mock;

    mock! {
        pub ProcessCollector {}

        #[async_trait]
        impl ProcessCollectionService for ProcessCollector {
            async fn collect_processes(&self) -> Result<CollectionResult, CollectionError>;
        }
    }

    #[tokio::test]
    async fn test_agent_with_mock_collector() {
        let mut mock_collector = MockProcessCollector::new();
        mock_collector
            .expect_collect_processes()
            .times(1)
            .returning(|| Ok(CollectionResult::default()));

        let agent = daemoneye_agent::new(Box::new(mock_collector));
        let result = agent.run_collection_cycle().await;

        assert!(result.is_ok());
    }
}

Integration Testing

Test component interactions and data flow:

#[tokio::test]
async fn test_database_integration() {
    let temp_dir = TempDir::new().unwrap();
    let db_path = temp_dir.path().join("test.db");

    let db = Database::new(&db_path).await.unwrap();
    db.create_schema().await.unwrap();

    let process = ProcessInfo::default();
    db.insert_process(&process).await.unwrap();

    let retrieved = db.get_process(process.pid).await.unwrap();
    assert_eq!(process.pid, retrieved.pid);
}

Performance Testing

Benchmark critical operations:

use criterion::{Criterion, black_box, criterion_group, criterion_main};

fn benchmark_process_collection(c: &mut Criterion) {
    let mut group = c.benchmark_group("process_collection");

    group.bench_function("collect_processes", |b| {
        b.iter(|| {
            let collector = ProcessCollector::new();
            black_box(collector.collect_processes())
        })
    });

    group.finish();
}

criterion_group!(benches, benchmark_process_collection);
criterion_main!(benches);

Deployment Considerations

Container Deployment

DaemonEye is designed for containerized deployment:

• Docker: Multi-stage builds for minimal images
• Kubernetes: DaemonSet for process monitoring
• Security: Non-root containers with minimal privileges
• Resource Limits: Configurable CPU and memory limits

Platform Support

Cross-platform support with platform-specific optimizations:

• Linux: Primary target with /proc filesystem access
• macOS: Native process enumeration with security framework
• Windows: Windows API process access with service deployment

Configuration Management

Hierarchical configuration with multiple sources:

1. Command-line flags (highest precedence)
2. Environment variables (DaemonEye_*)
3. User configuration file (~/.config/daemoneye/config.yaml)
4. System configuration file (/etc/daemoneye/config.yaml)
5. Embedded defaults (lowest precedence)

This technical documentation provides comprehensive information about DaemonEye’s implementation. For specific implementation details, consult the individual technical guides.

Core Monitoring Technical Specification

Overview

The Core Monitoring specification defines the fundamental process monitoring capabilities that form the foundation of DaemonEye. This includes process enumeration, executable integrity verification, SQL-based detection engine, and multi-channel alerting across the three-component architecture.

Process Collection Architecture

Cross-Platform Process Enumeration

DaemonEye uses a layered approach to process enumeration, providing a unified interface across different operating systems while allowing platform-specific optimizations.

Base Implementation (sysinfo crate)

Primary Interface: The sysinfo crate provides cross-platform process enumeration with consistent data structures.

use sysinfo::{Pid, ProcessExt, System, SystemExt};

pub struct ProcessCollector {
    system: System,
    config: CollectorConfig,
    hash_computer: Sha256HashComputer,
}

impl ProcessCollector {
    pub async fn enumerate_processes(&self) -> Result<Vec<ProcessRecord>> {
        self.system.refresh_processes();

        let mut processes = Vec::new();
        let collection_time =
            i64::try_from(SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis())
                .map_err(|_| "Timestamp overflow: system time exceeds i64::MAX milliseconds")?;

        for (pid, process) in self.system.processes() {
            let process_record = ProcessRecord {
                id: Uuid::new_v4(),
                scan_id: self.get_current_scan_id(),
                collection_time,
                pid: pid.as_u32(),
                ppid: process.parent().map(|p| p.as_u32()),
                name: process.name().to_string(),
                executable_path: process.exe().map(|p| p.to_path_buf()),
                command_line: process.cmd().to_vec(),
                start_time: process.start_time(),
                cpu_usage: process.cpu_usage(),
                memory_usage: Some(process.memory()),
                executable_hash: self.compute_executable_hash(process.exe()).await?,
                hash_algorithm: Some("sha256".to_string()),
                user_id: self.get_process_user(pid).await?,
                accessible: true,
                file_exists: process.exe().map(|p| p.exists()).unwrap_or(false),
                platform_data: self.get_platform_specific_data(pid).await?,
            };

            processes.push(process_record);
        }

        Ok(processes)
    }
}

Platform-Specific Enhancements

Kernel-level collection (eBPF on Linux, ETW on Windows, EndpointSecurity on macOS) is handled by commercial tiers, not by this repo. The Community tier uses user-space collection via sysinfo across all platforms.

Executable Integrity Verification

Hash Computation: SHA-256 hashing of executable files for integrity verification.

use sha2::{Digest, Sha256};
use std::io::Read;
use std::path::Path;

pub trait HashComputer: Send + Sync {
    fn compute_hash(&self, path: &Path) -> Result<Option<String>>;
    fn get_algorithm(&self) -> &'static str;
    fn buffer_size(&self) -> usize;
    fn set_buffer_size(&mut self, size: usize);
}

#[derive(Clone)]
pub struct Sha256HashComputer {
    buffer_size: usize,
}

impl Sha256HashComputer {
    pub fn new(buffer_size: usize) -> Self {
        Self { buffer_size }
    }
}

impl HashComputer for Sha256HashComputer {
    fn compute_hash(&self, path: &Path) -> Result<Option<String>> {
        if !path.exists() {
            return Ok(None);
        }

        let mut file = std::fs::File::open(path)?;
        let mut hasher = Sha256::new();
        let mut buffer = vec![0u8; self.buffer_size];

        loop {
            let bytes_read = file.read(&mut buffer)?;
            if bytes_read == 0 {
                break;
            }
            hasher.update(&buffer[..bytes_read]);
        }

        let hash = hasher.finalize();
        Ok(Some(format!("{:x}", hash)))
    }

    fn get_algorithm(&self) -> &'static str {
        "sha256"
    }

    fn buffer_size(&self) -> usize {
        self.buffer_size
    }

    fn set_buffer_size(&mut self, size: usize) {
        self.buffer_size = size;
    }
}

Performance Optimization: Asynchronous hash computation with configurable buffer sizes.

impl ProcessCollector {
    async fn compute_executable_hash(&self, path: Option<&Path>) -> Result<Option<String>> {
        let path = match path {
            Some(p) => p,
            None => return Ok(None),
        };

        // Skip hashing for system processes or inaccessible files
        if self.should_skip_hashing(path) {
            return Ok(None);
        }

        // Compute hash asynchronously
        let hash_computer = self.hash_computer.clone();
        let path = path.to_path_buf();

        tokio::task::spawn_blocking(move || hash_computer.compute_hash(&path)).await?
    }

    fn should_skip_hashing(&self, path: &Path) -> bool {
        // Skip hashing for system processes or temporary files
        let path_str = path.to_string_lossy();
        path_str.contains("/proc/")
            || path_str.contains("/sys/")
            || path_str.contains("/tmp/")
            || path_str.contains("\\System32\\")
    }
}

SQL-Based Detection Engine

SQL Validation and Security

AST Validation: Comprehensive SQL parsing and validation to prevent injection attacks.

use sqlparser::{ast::*, dialect::SQLiteDialect, parser::Parser};

pub struct SqlValidator {
    parser: Parser<SQLiteDialect>,
    allowed_functions: HashSet<String>,
    allowed_operators: HashSet<String>,
}

impl SqlValidator {
    pub fn new() -> Self {
        let dialect = SQLiteDialect {};
        let parser = Parser::new(&dialect);

        Self {
            parser,
            allowed_functions: Self::get_allowed_functions(),
            allowed_operators: Self::get_allowed_operators(),
        }
    }

    pub fn validate_query(&self, sql: &str) -> Result<ValidationResult> {
        let ast = self.parser.parse_sql(sql)?;

        for statement in &ast {
            match statement {
                Statement::Query(query) => self.validate_select_query(query)?,
                _ => return Err(ValidationError::ForbiddenStatement),
            }
        }

        Ok(ValidationResult::Valid)
    }

    fn validate_select_query(&self, query: &Query) -> Result<()> {
        self.validate_select_body(&query.body)?;

        if let Some(selection) = &query.selection {
            self.validate_where_clause(selection)?;
        }

        if let Some(group_by) = &query.group_by {
            self.validate_group_by(group_by)?;
        }

        if let Some(having) = &query.having {
            self.validate_having(having)?;
        }

        Ok(())
    }

    fn validate_select_body(&self, body: &SetExpr) -> Result<()> {
        match body {
            SetExpr::Select(select) => {
                for item in &select.projection {
                    self.validate_projection_item(item)?;
                }

                if let Some(from) = &select.from {
                    self.validate_from_clause(from)?;
                }
            }
            _ => return Err(ValidationError::UnsupportedSetExpr),
        }

        Ok(())
    }

    fn validate_projection_item(&self, item: &SelectItem) -> Result<()> {
        match item {
            SelectItem::UnnamedExpr(expr)
            | SelectItem::ExprWithAlias { expr, .. }
            | SelectItem::ExprWithAliases { expr, .. } => self.validate_expression(expr),
            // `Wildcard` is a tuple variant in sqlparser (carries
            // `WildcardAdditionalOptions`), so it must be matched as
            // `Wildcard(_)`, not a unit variant. Allow `SELECT *`.
            SelectItem::Wildcard(_) | SelectItem::QualifiedWildcard(..) => Ok(()),
        }
    }

    fn validate_expression(&self, expr: &Expr) -> Result<()> {
        match expr {
            Expr::Identifier(_) => Ok(()),
            Expr::Value(_) => Ok(()),
            Expr::BinaryOp { left, op, right } => {
                self.validate_operator(op)?;
                self.validate_expression(left)?;
                self.validate_expression(right)?;
                Ok(())
            }
            Expr::Function { name, args, .. } => {
                self.validate_function(name, args)?;
                Ok(())
            }
            Expr::Cast { expr, .. } => self.validate_expression(expr),
            Expr::Case { .. } => Ok(()), // Allow CASE expressions
            _ => Err(ValidationError::UnsupportedExpression),
        }
    }

    fn validate_function(&self, name: &ObjectName, args: &[FunctionArg]) -> Result<()> {
        let func_name = name.to_string().to_lowercase();

        if !self.allowed_functions.contains(&func_name) {
            return Err(ValidationError::ForbiddenFunction(func_name));
        }

        // Validate function arguments
        for arg in args {
            match arg {
                FunctionArg::Unnamed(FunctionArgExpr::Expr(expr)) => {
                    self.validate_expression(expr)?;
                }
                _ => return Err(ValidationError::UnsupportedFunctionArg),
            }
        }

        Ok(())
    }

    fn get_allowed_functions() -> HashSet<String> {
        [
            "count",
            "sum",
            "avg",
            "min",
            "max",
            "length",
            "substr",
            "upper",
            "lower",
            "datetime",
            "strftime",
            "unixepoch",
            "coalesce",
            "nullif",
            "ifnull",
        ]
        .iter()
        .map(|s| s.to_string())
        .collect()
    }
}

Detection Rule Execution

Sandboxed Execution: Safe execution of detection rules with resource limits.

pub struct DetectionEngine {
    db: redb::Database,
    sql_validator: SqlValidator,
    rule_manager: RuleManager,
    alert_manager: AlertManager,
}

impl DetectionEngine {
    pub async fn execute_rules(&self, scan_id: i64) -> Result<Vec<Alert>> {
        let rules = self.rule_manager.load_enabled_rules().await?;
        let mut alerts = Vec::new();

        for rule in rules {
            match self.execute_rule(&rule, scan_id).await {
                Ok(rule_alerts) => alerts.extend(rule_alerts),
                Err(e) => {
                    tracing::error!(
                        rule_id = %rule.id,
                        error = %e,
                        "Failed to execute detection rule"
                    );
                    // Continue with other rules
                }
            }
        }

        Ok(alerts)
    }

    async fn execute_rule(&self, rule: &DetectionRule, scan_id: i64) -> Result<Vec<Alert>> {
        // Validate SQL before execution
        self.sql_validator.validate_query(&rule.sql_query)?;

        // Execute with timeout and resource limits
        let execution_result = tokio::time::timeout(
            Duration::from_secs(30),
            self.execute_sql_query(&rule.sql_query, scan_id),
        )
        .await??;

        // Generate alerts from query results
        let mut alerts = Vec::new();
        for row in execution_result.rows {
            let alert = self
                .alert_manager
                .generate_alert(&rule, &row, scan_id)
                .await?;

            if let Some(alert) = alert {
                alerts.push(alert);
            }
        }

        Ok(alerts)
    }

    // `execute_sql_query` delegates to the DataFusion execution layer
    // described below — it does not touch a bare `redb::Database` handle.
}

Note on rule execution. redb is a key/value store with no SQL, prepare, or bind API, so detection rules are never run directly against a redb::Database. Per ADR-0006, validated/derived standard SQL is executed via an Apache DataFusion SessionContext whose catalog is populated by redb-backed per-collector TableProvider implementations. The runtime executor only ever sees the derived standard SQL produced by compile-time lowering — never the original custom dialect. The full pipeline (validation, predicate pushdown, schema catalog, execution, and degradation semantics) is specified in .kiro/specs/daemoneye-core-monitoring/design.md and spec/daemon_eye_spec_sql_to_ipc_detection_architecture.md.

Alert Generation and Management

Alert Data Model

Structured Alerts: Comprehensive alert structure with full context.

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Alert {
    pub id: Uuid,
    pub alert_time: i64,
    pub rule_id: String,
    pub title: String,
    pub description: String,
    pub severity: AlertSeverity,
    pub scan_id: Option<i64>,
    pub affected_processes: Vec<u32>,
    pub process_count: i32,
    pub alert_data: serde_json::Value,
    pub rule_execution_time_ms: Option<i64>,
    pub dedupe_key: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum AlertSeverity {
    Low,
    Medium,
    High,
    Critical,
}

impl Alert {
    pub fn new(rule: &DetectionRule, process_data: &ProcessRow, scan_id: Option<i64>) -> Self {
        let alert_time = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_millis() as i64;

        let dedupe_key = self.generate_dedupe_key(rule, process_data);

        Self {
            id: Uuid::new_v4(),
            alert_time,
            rule_id: rule.id.clone(),
            title: rule.name.clone(),
            description: rule.description.clone().unwrap_or_default(),
            severity: rule.severity.clone(),
            scan_id,
            affected_processes: vec![process_data.pid],
            process_count: 1,
            alert_data: serde_json::to_value(process_data).unwrap(),
            rule_execution_time_ms: None,
            dedupe_key,
        }
    }

    fn generate_dedupe_key(&self, rule: &DetectionRule, process_data: &ProcessRow) -> String {
        // Generate deduplication key based on rule and process characteristics
        format!(
            "{}:{}:{}:{}",
            rule.id,
            process_data.pid,
            process_data.name,
            process_data.executable_path.as_deref().unwrap_or("")
        )
    }
}

Alert Deduplication

Intelligent Deduplication: Prevent alert spam while maintaining security visibility.

pub struct AlertManager {
    db: redb::Database,
    dedupe_cache: Arc<Mutex<HashMap<String, Instant>>>,
    dedupe_window: Duration,
}

impl AlertManager {
    pub async fn generate_alert(
        &self,
        rule: &DetectionRule,
        process_data: &ProcessRow,
        scan_id: Option<i64>,
    ) -> Result<Option<Alert>> {
        let alert = Alert::new(rule, process_data, scan_id);

        // Check for deduplication
        if self.is_duplicate(&alert).await? {
            return Ok(None);
        }

        // Store alert in database
        self.store_alert(&alert).await?;

        // Update deduplication cache
        self.update_dedupe_cache(&alert).await?;

        Ok(Some(alert))
    }

    async fn is_duplicate(&self, alert: &Alert) -> Result<bool> {
        let mut cache = self.dedupe_cache.lock().await;

        if let Some(last_seen) = cache.get(&alert.dedupe_key) {
            if last_seen.elapsed() < self.dedupe_window {
                return Ok(true);
            }
        }

        Ok(false)
    }

    async fn update_dedupe_cache(&self, alert: &Alert) -> Result<()> {
        let mut cache = self.dedupe_cache.lock().await;
        cache.insert(alert.dedupe_key.clone(), Instant::now());
        Ok(())
    }
}

Multi-Channel Alert Delivery

Alert Sink Architecture

Pluggable Sinks: Flexible alert delivery through multiple channels.

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

pub struct AlertDeliveryManager {
    sinks: Vec<Box<dyn AlertSink>>,
    retry_policy: RetryPolicy,
    circuit_breaker: CircuitBreaker,
}

impl AlertDeliveryManager {
    pub async fn deliver_alert(&self, alert: &Alert) -> Result<Vec<DeliveryResult>> {
        let alert = alert.clone();

        // Collect futures without spawning (avoids 'static lifetime requirement)
        let delivery_futures: Vec<_> = self
            .sinks
            .iter()
            .map(|sink| {
                let alert = alert.clone();
                async move { sink.send(&alert).await }
            })
            .collect();

        // Execute all deliveries concurrently
        let results = futures::future::join_all(delivery_futures).await;

        Ok(results
            .into_iter()
            .map(|r| match r {
                Ok(dr) => dr,
                Err(e) => DeliveryResult::Failed(e.to_string()),
            })
            .collect())
    }

    async fn deliver_to_sink(&self, sink: &dyn AlertSink, alert: &Alert) -> DeliveryResult {
        // Apply circuit breaker
        if self.circuit_breaker.is_open(sink.name()) {
            return DeliveryResult::CircuitBreakerOpen;
        }

        // Retry with exponential backoff
        let mut attempt = 0;
        let mut delay = Duration::from_millis(100);

        loop {
            match sink.send(alert).await {
                Ok(result) => {
                    self.circuit_breaker.record_success(sink.name());
                    return result;
                }
                Err(e) => {
                    attempt += 1;
                    if attempt >= self.retry_policy.max_attempts {
                        self.circuit_breaker.record_failure(sink.name());
                        return DeliveryResult::Failed(e.to_string());
                    }

                    tokio::time::sleep(delay).await;
                    delay = std::cmp::min(delay * 2, Duration::from_secs(60));
                }
            }
        }
    }
}

Specific Sink Implementations

Stdout Sink:

pub struct StdoutSink {
    format: OutputFormat,
}

#[async_trait]
impl AlertSink for StdoutSink {
    async fn send(&self, alert: &Alert) -> Result<DeliveryResult> {
        let output = match self.format {
            OutputFormat::Json => serde_json::to_string_pretty(alert)?,
            OutputFormat::Text => self.format_text(alert),
            OutputFormat::Csv => self.format_csv(alert),
        };

        println!("{}", output);
        Ok(DeliveryResult::Success)
    }

    async fn health_check(&self) -> HealthStatus {
        HealthStatus::Healthy
    }

    fn name(&self) -> &str {
        "stdout"
    }
}

Syslog Sink:

pub struct SyslogSink {
    facility: SyslogFacility,
    tag: String,
    socket: UnixDatagram,
}

#[async_trait]
impl AlertSink for SyslogSink {
    async fn send(&self, alert: &Alert) -> Result<DeliveryResult> {
        let priority = self.map_severity_to_priority(&alert.severity);
        let timestamp = self.format_timestamp(alert.alert_time);
        let message = format!(
            "<{}>{} {} {}: {}",
            priority, timestamp, self.tag, alert.title, alert.description
        );

        self.socket.send(message.as_bytes()).await?;
        Ok(DeliveryResult::Success)
    }

    async fn health_check(&self) -> HealthStatus {
        // Check if syslog socket is accessible
        HealthStatus::Healthy
    }

    fn name(&self) -> &str {
        "syslog"
    }
}

Webhook Sink:

pub struct WebhookSink {
    url: Url,
    client: reqwest::Client,
    headers: HeaderMap,
    timeout: Duration,
}

#[async_trait]
impl AlertSink for WebhookSink {
    async fn send(&self, alert: &Alert) -> Result<DeliveryResult> {
        let payload = serde_json::to_value(alert)?;

        let response = self
            .client
            .post(self.url.clone())
            .headers(self.headers.clone())
            .json(&payload)
            .timeout(self.timeout)
            .send()
            .await?;

        if response.status().is_success() {
            Ok(DeliveryResult::Success)
        } else {
            Err(AlertDeliveryError::HttpError(response.status()))
        }
    }

    async fn health_check(&self) -> HealthStatus {
        // Perform health check by sending a test request
        match self
            .client
            .get(self.url.clone())
            .timeout(Duration::from_secs(5))
            .send()
            .await
        {
            Ok(response) if response.status().is_success() => HealthStatus::Healthy,
            _ => HealthStatus::Unhealthy,
        }
    }

    fn name(&self) -> &str {
        "webhook"
    }
}

Performance Requirements and Optimization

Process Collection Performance

Target Metrics:

• Process Enumeration: <5 seconds for 10,000+ processes
• CPU Usage: <5% sustained during continuous monitoring
• Memory Usage: <100MB resident under normal operation
• Hash Computation: Complete within enumeration time

Optimization Strategies:

impl ProcessCollector {
    async fn enumerate_processes_optimized(&self) -> Result<Vec<ProcessRecord>> {
        let start_time = Instant::now();

        // Use parallel processing for hash computation
        let (processes, hash_tasks): (Vec<_>, Vec<_>) = self
            .collect_basic_process_data()
            .into_iter()
            .partition(|p| p.executable_path.is_none());

        // Compute hashes in parallel
        let hash_results =
            futures::future::join_all(hash_tasks.into_iter().map(|p| self.compute_hash_async(p)))
                .await;

        let mut all_processes = processes;
        all_processes.extend(hash_results.into_iter().flatten());

        let duration = start_time.elapsed();
        tracing::info!(
            process_count = all_processes.len(),
            duration_ms = duration.as_millis(),
            "Process enumeration completed"
        );

        Ok(all_processes)
    }
}

Detection Engine Performance

Target Metrics:

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

Optimization Strategies:

impl DetectionEngine {
    async fn execute_rules_optimized(&self, scan_id: i64) -> Result<Vec<Alert>> {
        let rules = self.rule_manager.load_enabled_rules().await?;

        // Group rules by complexity for optimal scheduling
        let (simple_rules, complex_rules) = self.categorize_rules(rules);

        // Execute simple rules in parallel
        let simple_alerts = futures::future::join_all(
            simple_rules
                .into_iter()
                .map(|rule| self.execute_rule(rule, scan_id)),
        )
        .await;

        // Execute complex rules sequentially to avoid resource contention
        let mut complex_alerts = Vec::new();
        for rule in complex_rules {
            let alerts = self.execute_rule(rule, scan_id).await?;
            complex_alerts.extend(alerts);
        }

        // Combine results
        let mut all_alerts = Vec::new();
        for result in simple_alerts {
            all_alerts.extend(result?);
        }
        all_alerts.extend(complex_alerts);

        Ok(all_alerts)
    }
}

Error Handling and Recovery

Graceful Degradation

Process Collection Failures:

impl ProcessCollector {
    async fn enumerate_processes_with_fallback(&self) -> Result<Vec<ProcessRecord>> {
        match self.enumerate_processes_enhanced().await {
            Ok(processes) => Ok(processes),
            Err(e) => {
                tracing::warn!("Enhanced enumeration failed, falling back to basic: {}", e);
                self.enumerate_processes_basic().await
            }
        }
    }
}

Detection Engine Failures:

impl DetectionEngine {
    async fn execute_rule_with_recovery(
        &self,
        rule: &DetectionRule,
        scan_id: i64,
    ) -> Result<Vec<Alert>> {
        match self.execute_rule(rule, scan_id).await {
            Ok(alerts) => Ok(alerts),
            Err(e) => {
                tracing::error!(
                    rule_id = %rule.id,
                    error = %e,
                    "Rule execution failed, marking as disabled"
                );

                // Disable problematic rules to prevent repeated failures
                self.rule_manager.disable_rule(&rule.id).await?;
                Ok(Vec::new())
            }
        }
    }
}

Resource Management

Memory Pressure Handling:

const MIN_HASH_BUFFER_SIZE: usize = 4 * 1024;

impl ProcessCollector {
    async fn handle_memory_pressure(&mut self) -> Result<()> {
        let memory_usage = self.get_memory_usage()?;

        if memory_usage > self.config.memory_threshold {
            tracing::warn!("Memory pressure detected, reducing batch size");

            // Reduce batch size for hash computation without dropping below the minimum buffer
            let current = self.hash_computer.buffer_size();
            let new_size = (current / 2).max(MIN_HASH_BUFFER_SIZE);
            if new_size < current {
                self.hash_computer.set_buffer_size(new_size);
            }

            // Trigger garbage collection
            tokio::task::yield_now().await;
        }

        Ok(())
    }
}

This core monitoring specification provides the foundation for DaemonEye’s process monitoring capabilities, ensuring high performance, security, and reliability across all supported platforms.

EventBus Architecture

Overview

The daemoneye-eventbus provides a local cross-platform IPC pub/sub messaging system designed specifically for multi-collector coordination within a single DaemonEye system. It enables collectors to communicate with the daemoneye-agent on the same host through a hierarchical topic structure with support for workflow tracking and forensic analysis.

Scope: The EventBus is designed for local IPC communication only. All collectors and the agent must run on the same system. For multi-system deployments, each system runs its own independent EventBus broker within its daemoneye-agent instance.

Key Features

• Cross-platform transport: Unix domain sockets (Linux/macOS) and named pipes (Windows)
• Hierarchical topics: Up to 4-level topic structure with wildcard matching
• Correlation metadata: Track events across multi-collector workflows
• Embedded broker: Runs within daemoneye-agent orchestrator
• Access control: Three-level access control (Public, Restricted, Privileged)
• High performance: 10,000+ messages/second throughput, sub-millisecond latency

Topic Hierarchy

Event Topics (Data Flow)

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

Process Events (events.process.*)

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

Future Extensions

• events.network.* - Network monitoring events (netmond)
• events.filesystem.* - Filesystem monitoring events (fsmond)
• events.performance.* - Performance monitoring events (perfmond)

Control Topics (Management Flow)

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

Collector Management (control.collector.*)

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

Agent Orchestration (control.agent.*)

Health Monitoring (control.health.*)

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

Wildcard Matching

The EventBus supports two types of wildcards for flexible subscriptions:

Single-level Wildcard (+)

Matches exactly one segment:

// Subscribe to lifecycle events from all collector types
let pattern = "events.+.lifecycle";
// Matches: events.process.lifecycle, events.network.lifecycle
// Does not match: events.process.metadata

Multi-level Wildcard (#)

Matches zero or more segments (must be at the end):

// Subscribe to all process events
let pattern = "events.process.#";
// Matches: events.process.lifecycle, events.process.metadata, events.process.tree

// Subscribe to all control messages
let pattern = "control.#";
// Matches: control.collector.lifecycle, control.health.heartbeat

Correlation Metadata

The EventBus supports comprehensive correlation tracking for multi-collector workflows and forensic analysis.

Basic Correlation

use daemoneye_eventbus::CorrelationMetadata;

// Create correlation metadata
let metadata = CorrelationMetadata::new("workflow-123".to_string())
    .with_stage("collection".to_string())
    .with_tag("source".to_string(), "procmond".to_string());

Hierarchical Correlation

Track events across multiple stages of analysis:

// Root correlation for entire workflow
let root_metadata = CorrelationMetadata::new("threat-analysis-001".to_string())
    .with_stage("detection".to_string())
    .with_tag("workflow".to_string(), "suspicious_process_analysis".to_string());

// Collection stage
let collection_metadata = root_metadata.create_child("collection-001".to_string())
    .with_stage("collection".to_string());

// Analysis stage
let analysis_metadata = collection_metadata.create_child("analysis-001".to_string())
    .with_stage("analysis".to_string());

// Alert generation stage
let alert_metadata = analysis_metadata.create_child("alert-001".to_string())
    .with_stage("alerting".to_string());

Correlation Filtering

Filter events based on correlation metadata:

use daemoneye_eventbus::{CorrelationFilter, EventSubscription};

// Filter by root correlation ID (entire workflow)
let filter = CorrelationFilter::new()
    .with_root_id("threat-analysis-001".to_string())
    .with_stage("analysis".to_string())
    .with_required_tag("workflow".to_string(), "suspicious_process_analysis".to_string());

// Use in subscription
let subscription = EventSubscription {
    subscriber_id: "forensic-analyzer".to_string(),
    correlation_filter: Some(filter),
    topic_patterns: Some(vec!["events.process.#".to_string()]),
    enable_wildcards: true,
    // ... other fields
};

Use Cases

Multi-Collector Workflows (Local System)

Track events across multiple collectors in a cascading analysis workflow on the same system:

// Root correlation for entire local workflow
let root_correlation = CorrelationMetadata::new("workflow-id".to_string())
    .with_stage("detection".to_string())
    .with_tag("workflow".to_string(), "suspicious_process_analysis".to_string())
    .with_tag("host".to_string(), "localhost".to_string());

// Process collection stage (procmond)
let collection_correlation = root_correlation.create_child("collection-id".to_string())
    .with_stage("collection".to_string());

// Binary analysis stage (local analyzer)
let analysis_correlation = collection_correlation.create_child("analysis-id".to_string())
    .with_stage("analysis".to_string());

// Alert generation stage (daemoneye-agent)
let alert_correlation = analysis_correlation.create_child("alert-id".to_string())
    .with_stage("alerting".to_string());

Forensic Investigation Tracking (Local System)

Track all events related to a security investigation on a single host:

let investigation_id = "incident-2024-001";
let forensic_metadata = CorrelationMetadata::new(investigation_id.to_string())
    .with_stage("forensic_analysis".to_string())
    .with_tag("investigation_id".to_string(), investigation_id.to_string())
    .with_tag("analyst".to_string(), "security_team".to_string())
    .with_tag("severity".to_string(), "critical".to_string())
    .with_tag("incident_type".to_string(), "malware_detection".to_string())
    .with_tag("host".to_string(), "compromised-server-01".to_string());

// Filter for all local events in this investigation
let forensic_filter = CorrelationFilter::new()
    .with_required_tag("investigation_id".to_string(), investigation_id.to_string())
    .with_required_tag("severity".to_string(), "critical".to_string());

Local Workflow Tracing

Track events across local collector components on a single system:

let trace_metadata = CorrelationMetadata::new("trace-id".to_string())
    .with_stage("local_collection".to_string())
    .with_tag("component".to_string(), "procmond".to_string())
    .with_tag("host".to_string(), "server-01".to_string())
    .with_tag("collector_type".to_string(), "process_monitor".to_string());

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
• Requires component registration

Privileged Topics

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

Embedded Broker

The daemoneye-agent runs an embedded EventBus broker that:

Broker Responsibilities

• Topic Management: Manages topic subscriptions and message routing
• Access Control: Enforces topic-level access control policies
• Correlation Tracking: Tracks correlation metadata for workflow coordination
• Statistics: Provides message statistics and health monitoring
• Connection Management: Manages client connections and reconnection

Broker Configuration

The broker is configured through the daemoneye-agent configuration:

eventbus:
  socket_path: /tmp/daemoneye-broker.sock  # Unix socket path
  max_connections: 100                      # Maximum concurrent connections
  message_buffer_size: 10000                # Message buffer size per subscriber
  enable_statistics: true                   # Enable statistics collection

Broker Statistics

The broker tracks the following statistics:

• Messages published per topic
• Messages delivered per subscriber
• Active subscribers per topic
• Message delivery latency
• Connection count and status

Performance Characteristics

Throughput

• Message Rate: 10,000+ messages per second
• Concurrent Subscribers: 100+ subscribers per topic
• Message Size: Up to 1MB per message

Latency

• Local IPC: <1ms p99 for local IPC, validated in CI on Linux and macOS by a dedicated criterion benchmark. Windows and FreeBSD are informational only (not gated in CI).
• Message Routing: < 100μs per message
• Correlation Lookup: < 10μs per filter

Resource Usage

• Memory: < 10MB per 1000 subscribers
• CPU: < 1% for message routing
• Disk: No persistent storage (in-memory only)

Security Considerations

Transport Security

• Unix Sockets: File permissions 0600 (owner read/write only)
• Named Pipes: Appropriate Windows security descriptors
• Process Isolation: Each collector runs in separate process

Message Security

• Serialization: Uses postcard for efficient binary protocol
• Validation: All incoming messages validated
• Size Limits: Enforce maximum message sizes (1MB default)

Access Control

• Topic-level: Enforced by broker based on component identity
• Component Registration: Required for restricted topics
• Authentication: Required for privileged topics

Integration Examples

Publishing Events

use daemoneye_eventbus::{
    CollectionEvent, DaemoneyeEventBus, ProcessEvent, CorrelationMetadata,
};

// Create correlation metadata
let metadata = CorrelationMetadata::new("workflow-123".to_string())
    .with_stage("collection".to_string())
    .with_tag("source".to_string(), "procmond".to_string());

// Create process event
let event = CollectionEvent::Process(ProcessEvent {
    pid: 1234,
    name: "suspicious_process".to_string(),
    // ... other fields
});

// Publish with correlation metadata
event_bus.publish(event, metadata.correlation_id.clone()).await?;

Subscribing to Events

use daemoneye_eventbus::{EventSubscription, SourceCaps, CorrelationFilter};

// Create subscription with correlation filter
let subscription = EventSubscription {
    subscriber_id: "forensic-analyzer".to_string(),
    capabilities: SourceCaps {
        event_types: vec!["process".to_string()],
        collectors: vec!["procmond".to_string()],
        max_priority: 5,
    },
    event_filter: None,
    correlation_filter: Some(
        CorrelationFilter::new()
            .with_root_id("workflow-123".to_string())
            .with_required_tag("workflow".to_string(), "threat_analysis".to_string())
    ),
    topic_patterns: Some(vec!["events.process.#".to_string()]),
    enable_wildcards: true,
    include_control: false,  // default: only receive Event messages
};

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

// Receive events
while let Some(bus_event) = receiver.recv().await {
    println!("Received event: {:?}", bus_event);
}

To also receive control messages (lifecycle commands, task assignments):

let subscription = EventSubscription {
    subscriber_id: "agent-aware-collector".to_string(),
    // ... other fields
    topic_patterns: Some(vec!["control.collector.lifecycle".to_string()]),
    include_control: true,
    ..Default::default()
};

let (mut event_rx, mut control_rx) = event_bus.subscribe_with_control(subscription).await?;

// Receive events and control messages on parallel channels
loop {
    tokio::select! {
        Some(bus_event) = event_rx.recv() => {
            println!("Received event: {:?}", bus_event);
        }
        Some(control_msg) = control_rx.recv() => {
            println!("Received control message: {:?}", control_msg);
        }
        else => break,
    }
}

Troubleshooting

Common Issues

Connection Refused

Symptom: Cannot connect to EventBus broker

Solution:

1. Verify daemoneye-agent is running
2. Check socket path configuration
3. Verify file permissions on Unix socket

No Messages Received

Symptom: Subscriber not receiving messages

Solution:

1. Verify topic pattern matches published topics
2. Check correlation filter criteria
3. Verify access control permissions

High Latency

Symptom: Message delivery is slow

Solution:

1. Check message buffer size configuration
2. Verify subscriber is processing messages quickly
3. Monitor broker statistics for bottlenecks

Further Reading

• Topic Hierarchy Documentation
• Correlation Metadata Documentation
• EventBus API Reference

RPC and EventBus Architecture

This document describes the RPC (Remote Procedure Call) and EventBus architecture that enables multi-collector coordination and lifecycle management in DaemonEye.

Overview

DaemonEye uses a dual-protocol architecture for inter-component communication:

1. IPC Protocol: Protobuf over Unix sockets/named pipes for CLI-to-agent communication
2. EventBus Protocol: Topic-based pub/sub messaging for collector-to-agent coordination

The daemoneye-agent runs an embedded EventBus broker that provides:

• Topic-based message routing with wildcard patterns
• RPC patterns for collector lifecycle management
• Correlation metadata for distributed tracing
• Health monitoring and metrics collection

Architecture Diagram

flowchart TB
    subgraph "daemoneye-agent Process"
        AGENT[Agent Core]
        BROKER[Embedded EventBus Broker]
        RPC[RPC Service]
        IPC[IPC Server]
        PM[Process Manager]

        AGENT --> BROKER
        AGENT --> RPC
        AGENT --> IPC
        AGENT --> PM
        RPC --> BROKER
        PM --> RPC
    end

    subgraph "Collector Processes"
        PROC[procmond]
        NET[netmond]
        FS[fsmond]
    end

    subgraph "CLI Process"
        CLI[daemoneye-cli]
    end

    PROC -->|EventBus Topics| BROKER
    NET -->|EventBus Topics| BROKER
    FS -->|EventBus Topics| BROKER

    CLI -->|IPC Protobuf| IPC

    PM -->|RPC Lifecycle| PROC
    PM -->|RPC Lifecycle| NET
    PM -->|RPC Lifecycle| FS

EventBus Topic Hierarchy

The EventBus uses a hierarchical topic structure for message routing:

Event Topics

• events.process.* - Process monitoring events

  • events.process.lifecycle - Process start/stop events
  • events.process.metadata - Process metadata updates
  • events.process.tree - Process tree relationships
  • events.process.integrity - Executable integrity events
  • events.process.anomaly - Anomaly detection events
  • events.process.batch - Batch process updates

• events.network.* - Network monitoring events (future)

• events.filesystem.* - Filesystem monitoring events (future)

• events.performance.* - Performance monitoring events (future)

Control Topics

• control.collector.* - Collector management

  • control.collector.lifecycle - Start/stop/restart commands
  • control.collector.config - Configuration updates
  • control.collector.task - Task distribution

• control.health.* - Health monitoring

  • control.health.heartbeat - Heartbeat messages
  • control.health.status - Status reports
  • control.health.diagnostics - Diagnostic information

Wildcard Patterns

The EventBus supports two wildcard patterns:

• + - Single-level wildcard (e.g., events.process.+ matches events.process.lifecycle)
• # - Multi-level wildcard (e.g., events.# matches all event topics)

RPC Patterns

Collector Lifecycle Operations

The RPC service provides structured request/response patterns for collector management:

Start Collector

use daemoneye_eventbus::rpc::{CollectorRpcClient, CollectorLifecycleRequest, RpcRequest, CollectorOperation};
use std::time::Duration;

let request = RpcRequest::lifecycle(
    "agent-id".to_string(),
    "control.collector.procmond".to_string(),
    CollectorOperation::Start,
    CollectorLifecycleRequest::start("procmond", None),
    Duration::from_secs(30)
);

let response = rpc_client.call(request, Duration::from_secs(30)).await?;

Stop Collector

let request = RpcRequest::lifecycle(
    "agent-id".to_string(),
    "control.collector.procmond".to_string(),
    CollectorOperation::Stop,
    CollectorLifecycleRequest::stop("procmond", true), // graceful=true
    Duration::from_secs(60)
);

let response = rpc_client.call(request, Duration::from_secs(60)).await?;

Health Check

let request = RpcRequest::health_check(
    "agent-id".to_string(),
    "control.collector.procmond".to_string(),
    Duration::from_secs(10)
);

let response = rpc_client.call(request, Duration::from_secs(10)).await?;

RPC Message Structure

All RPC messages include:

• Correlation ID: Unique identifier for request/response matching
• Timestamp: Request creation time
• Timeout: Maximum execution time
• Operation: Type of operation (Start, Stop, Restart, HealthCheck, etc.)
• Payload: Operation-specific data

Error Handling

RPC calls can fail with:

• Timeout: Operation exceeded timeout duration
• NotFound: Target collector not found
• InvalidOperation: Operation not supported
• ExecutionError: Operation failed during execution
• CommunicationError: Network or transport error

Correlation Metadata

All EventBus messages include correlation metadata for distributed tracing:

pub struct CorrelationMetadata {
    pub correlation_id: String,
    pub parent_correlation_id: Option<String>,
    pub root_correlation_id: String,
    pub sequence_number: u64,
    pub workflow_stage: Option<String>,
    pub tags: HashMap<String, String>,
}

This enables:

• Request/response correlation across multiple hops
• Workflow tracking for complex operations
• Forensic analysis of event chains
• Performance profiling of distributed operations

Multi-Collector Coordination

Task Distribution

The agent distributes tasks to collectors based on capabilities:

1. Agent receives detection task (e.g., SQL query)
2. Agent determines required collector capabilities
3. Agent publishes task to appropriate topic (e.g., control.collector.task)
4. Collectors with matching capabilities receive and execute task
5. Collectors publish results to result topic (e.g., events.process.batch)
6. Agent aggregates results and generates alerts

Result Aggregation

Results from multiple collectors are aggregated using:

• Correlation IDs: Match results to original request
• Sequence Numbers: Order results from same collector
• Deduplication: Remove duplicate results across collectors
• Timeout Handling: Handle slow or failed collectors gracefully

Load Balancing

When multiple instances of the same collector type are available:

• Tasks are distributed round-robin across instances
• Failed instances are detected via health checks
• Tasks are automatically redistributed to healthy instances
• Collectors can advertise capacity limits

Configuration

Broker Configuration

broker:
  socket_path: /tmp/daemoneye-eventbus.sock
  startup_timeout_seconds: 30
  max_subscribers: 100
  message_buffer_size: 10000
  enable_metrics: true

RPC Configuration

rpc:
  default_timeout_seconds: 30
  health_check_interval_seconds: 60
  enable_correlation_tracking: true
  max_pending_requests: 1000

Process Manager Configuration

process_manager:
  graceful_shutdown_timeout_seconds: 60
  force_shutdown_timeout_seconds: 5
  health_check_interval_seconds: 120
  enable_auto_restart: true
  max_restart_attempts: 3
  restart_backoff_seconds: 5

Performance Characteristics

EventBus Throughput

• Message Rate: 10,000+ messages/second
• Latency: Sub-millisecond for local delivery
• Memory: Bounded by message_buffer_size
• CPU: <1% overhead for message routing

RPC Performance

• Request Rate: 1,000+ requests/second
• Latency: <10ms for local RPC calls
• Timeout Handling: Configurable per operation
• Concurrent Requests: Limited by max_pending_requests

Security Considerations

Access Control

• EventBus broker runs within daemoneye-agent process boundary
• Only local processes can connect via Unix sockets/named pipes
• No network exposure of EventBus or RPC services
• Collectors must authenticate via capability negotiation

Message Validation

• All messages validated against protobuf schema
• Topic patterns validated before subscription
• RPC payloads validated before execution
• Correlation IDs validated for uniqueness

Resource Limits

• Maximum subscribers per topic
• Maximum message buffer size
• Maximum pending RPC requests
• Timeout enforcement for all operations

Monitoring and Observability

Metrics

The EventBus and RPC service expose metrics for:

• Message publish/subscribe rates
• RPC request/response rates
• Error rates by operation type
• Latency histograms
• Active subscriber counts
• Message buffer utilization

Health Checks

Health checks verify:

• Broker is running and accepting connections
• RPC service is responding to requests
• Collectors are sending heartbeats
• Message buffers are not full
• No excessive error rates

Logging

Structured logs include:

• Correlation IDs for request tracing
• Operation types and durations
• Error details with context
• Performance metrics
• Resource utilization

Troubleshooting

Common Issues

Broker fails to start:

• Check socket_path is writable
• Verify no other process using socket
• Check startup_timeout_seconds is sufficient

RPC timeouts:

• Increase default_timeout_seconds
• Check collector health status
• Verify network connectivity
• Review collector logs for errors

Message delivery failures:

• Check message_buffer_size is sufficient
• Verify subscriber is connected
• Review topic pattern matching
• Check for backpressure conditions

Collector not receiving tasks:

• Verify collector capabilities match task requirements
• Check topic subscription patterns
• Review correlation IDs for matching
• Verify collector is registered with broker

Future Enhancements

• Federation: Multi-agent coordination across network
• Persistence: Message persistence for reliability
• Compression: Message compression for large payloads
• Encryption: End-to-end encryption for sensitive data
• Rate Limiting: Per-subscriber rate limiting
• Priority Queues: Priority-based message delivery

Inter-Process Communication (IPC)

Overview

DaemonEye uses a secure, high-performance IPC system to coordinate between its three components (procmond, daemoneye-agent, and daemoneye-cli). The IPC layer provides reliable cross-platform communication using native OS primitives while maintaining strict security boundaries.

Transport Architecture

The IPC system is built on the interprocess crate, which provides a unified interface for local inter-process communication across different operating systems:

• Transport: Cross-platform local sockets via interprocess::local_socket
• Protocol: Protocol Buffers with CRC32 integrity validation
• Framing: Length-delimited frames with error detection
• Security: Platform-appropriate permissions and connection limiting
• Integration: Full async/await support with Tokio runtime

Platform-Specific Transports

DaemonEye automatically selects the optimal IPC transport for each platform:

• Linux/macOS: Unix domain sockets for maximum performance and security
• Windows: Named pipes with appropriate security descriptors
• All Platforms: Identical API and behavior regardless of underlying transport

Protocol Design

Message Framing

Each IPC message uses a simple, robust framing protocol:

[Length: u32][CRC32: u32][Protobuf Message: N bytes]

• Length Field: Message size in bytes (little-endian)
• CRC32 Checksum: Integrity validation of message content
• Message Payload: Protocol Buffer-encoded data

Security Features

• Local-only: No network exposure - all communication is local to the host
• Permission Control: Unix sockets use 0600 permissions (owner-only access)
• Connection Limits: Configurable maximum concurrent connections
• Input Validation: All messages validated before processing
• Resource Limits: Configurable frame size limits prevent DoS attacks

Configuration

The IPC system is configured through the IpcConfig structure:

pub struct IpcConfig {
    pub endpoint_path: String,
    pub max_frame_bytes: usize,
    pub read_timeout_ms: u64,
    pub write_timeout_ms: u64,
    pub max_connections: usize,
    pub crc32_variant: Crc32Variant,
}

Configuration Parameters

• endpoint_path: Platform-specific IPC endpoint location
• max_frame_bytes: Maximum message size (default: 1MB)
• read_timeout_ms: Read operation timeout (default: 30 seconds)
• write_timeout_ms: Write operation timeout (default: 10 seconds)
• max_connections: Maximum concurrent connections (default: 16)
• crc32_variant: Checksum algorithm variant (default: IEEE 802.3)

Endpoint Configuration

Default Paths

• Unix/macOS: /var/run/daemoneye/procmond.sock
• Windows: \\.\pipe\daemoneye\procmond

Custom Endpoints

You can specify custom endpoints in the configuration:

# Example configuration (choose one based on platform)
ipc:
  # Unix/macOS
  endpoint_path: /tmp/custom-daemoneye.sock
  # Windows (alternative)
  # endpoint_path: "\\\\.\\pipe\\custom-daemoneye"

Endpoint Permissions

• Unix sockets: Directory permissions 0700, socket permissions 0600
• Windows named pipes: Restricted to the current user by default
• All platforms: No network access - local communication only

Error Handling and Reliability

Connection Management

• Automatic Reconnection: Clients automatically reconnect with exponential backoff
• Graceful Degradation: Components handle IPC failures without crashing
• Timeout Handling: Configurable timeouts prevent hanging operations
• Connection Limiting: Server-side connection limits prevent resource exhaustion

Error Types

The IPC layer provides detailed error information:

use std::io;

pub enum IpcError {
    Timeout,                                    // Operation timed out
    TooLarge { size: usize, max_size: usize },  // Message exceeds size limit
    CrcMismatch { expected: u32, actual: u32 }, // Data corruption detected
    Io(io::Error),                              // Underlying I/O error
    Decode(prost::DecodeError),                 // Protobuf decoding error
    Encode(String),                             // Protobuf encoding error
    PeerClosed,                                 // Connection closed by peer
    InvalidLength { length: usize },            // Invalid message length
}

Performance Characteristics

• Low Latency: Direct process-to-process communication without network stack
• High Throughput: Efficient binary protocol with minimal overhead
• Memory Efficient: Zero-copy deserialization where possible
• Async/Await: Non-blocking operations with Tokio integration

Troubleshooting

Common Issues

1. Permission Denied

   • Check socket file/directory permissions
   • Ensure processes run as same user or with appropriate privileges

2. Connection Refused

   • Verify the server component (procmond) is running
   • Check endpoint path configuration matches between components

3. Timeout Errors

   • Increase timeout values in configuration if needed
   • Check system load and process responsiveness

Diagnostic Commands

# Check IPC status
daemoneye-cli health-check --verbose

# Verify endpoint accessibility
ls -la /var/run/daemoneye/  # Unix/macOS

# Test IPC connectivity
daemoneye-cli ipc test

macOS Process Collector

Overview

The macOS Process Collector provides enhanced process monitoring capabilities specifically designed for macOS systems. It leverages well-maintained third-party crates to deliver comprehensive process metadata collection, security analysis, and system integration while maintaining safety and accuracy.

Key Features

Enhanced Third-Party Crate Integration

The macOS collector uses a carefully selected set of third-party crates instead of direct system calls:

• sysinfo - Cross-platform process enumeration with macOS optimizations
• security-framework - macOS Security framework integration for code signing and entitlements
• core-foundation - Core Foundation API access for system integration
• mac-sys-info - System information and SIP (System Integrity Protection) awareness

Safety and Reliability

• No unsafe code - All operations use safe Rust abstractions
• Graceful error handling - Comprehensive error handling with structured error types
• Graceful degradation - Continues with reduced functionality when APIs are unavailable
• Sandboxing support - Handles macOS app sandboxing restrictions properly

Core Capabilities

Process Enumeration

The collector provides comprehensive process enumeration with macOS-specific enhancements:

use procmond::macos_collector::{EnhancedMacOSCollector, MacOSCollectorConfig};
use procmond::process_collector::ProcessCollectionConfig;

async fn example_macos_collection() -> Result<(), Box<dyn std::error::Error>> {
    let base_config = ProcessCollectionConfig::default();
    let macos_config = MacOSCollectorConfig {
        collect_entitlements: true,
        check_sip_protection: true,
        collect_code_signing: true,
        collect_bundle_info: true,
        handle_sandboxed_processes: true,
    };

    let collector = EnhancedMacOSCollector::new(base_config, macos_config)?;
    let (events, stats) = collector.collect_processes().await?;
    Ok(())
}

Security Analysis

Entitlements Detection

The collector analyzes process entitlements using path-based heuristics and Security framework integration:

• System processes (/System/, /usr/) - Typically have system access, not sandboxed
• App bundles (.app/) - Usually sandboxed with limited filesystem access
• Other executables - Minimal entitlements assumed

Code Signing Validation

Determines code signing status based on process characteristics:

• System processes and app bundles - Assumed to be signed (typically by Apple)
• Other executables - May be unsigned
• Certificate validation - Basic validation through Security framework

System Integrity Protection (SIP)

Detects SIP status and identifies SIP-protected processes:

• SIP detection - Uses csrutil status command with fallback
• Protected paths - Identifies processes in SIP-protected locations
• Safe defaults - Assumes SIP enabled for security

Process Metadata Collection

Basic Information

• Process ID (PID) and parent PID (PPID)
• Process name and executable path
• Command line arguments
• Start time and collection timestamp
• User ID and accessibility status

Enhanced Metadata

• CPU usage percentage
• Memory usage (resident and virtual)
• Memory footprint analysis
• Process architecture detection
• Bundle information extraction

macOS-Specific Attributes

• Entitlements analysis (debugging, system access, sandboxing)
• SIP protection status
• Code signing information
• Bundle metadata (name, version, bundle ID)
• Hardened runtime detection

Configuration Options

MacOSCollectorConfig

pub struct MacOSCollectorConfig {
    /// Whether to collect process entitlements information
    pub collect_entitlements: bool,
    /// Whether to check SIP protection status
    pub check_sip_protection: bool,
    /// Whether to collect code signing information
    pub collect_code_signing: bool,
    /// Whether to collect bundle information
    pub collect_bundle_info: bool,
    /// Whether to handle sandboxed processes gracefully
    pub handle_sandboxed_processes: bool,
}

Default Configuration

impl Default for MacOSCollectorConfig {
    fn default() -> Self {
        Self {
            collect_entitlements: true,
            check_sip_protection: true,
            collect_code_signing: true,
            collect_bundle_info: true,
            handle_sandboxed_processes: true,
        }
    }
}

Architecture

Component Structure

graph TD
    A[EnhancedMacOSCollector] --> B[sysinfo System]
    A --> C[Security Framework]
    A --> D[SIP Detection]
    A --> E[Bundle Analysis]

    B --> F[Process Enumeration]
    B --> G[Memory Information]
    B --> H[CPU Usage]

    C --> I[Code Signing]
    C --> J[Entitlements]

    D --> K[csrutil Command]
    D --> L[Path Analysis]

    E --> M[Bundle Name Extraction]
    E --> N[App Bundle Detection]

Data Flow

1. System Refresh - sysinfo refreshes process list
2. Process Enhancement - Each process gets enhanced with macOS-specific metadata
3. Security Analysis - Entitlements, code signing, and SIP status determined
4. Bundle Processing - App bundle information extracted
5. Event Generation - ProcessEvent objects created with comprehensive metadata

Error Handling

Structured Error Types

#[derive(Debug, Error)]
pub enum MacOSCollectionError {
    #[error("Security framework error: {0}")]
    SecurityFramework(String),

    #[error("System information error: {0}")]
    SystemInfo(String),

    #[error("Process filesystem error: {0}")]
    ProcessFs(String),

    #[error("Core Foundation error: {0}")]
    CoreFoundation(String),
}

Graceful Degradation

The collector handles various failure scenarios gracefully:

• Security framework unavailable - Falls back to path-based heuristics
• SIP detection failure - Assumes SIP enabled for security
• Process access denied - Continues with available processes
• Sandboxing restrictions - Handles limited access scenarios

Performance Characteristics

Target Metrics

• Process enumeration - < 5 seconds for 10,000+ processes
• Memory usage - < 100MB during collection
• CPU overhead - < 5% sustained during monitoring
• Collection rate - > 1,000 processes per second

Optimization Features

• Efficient process lookup - Optimized sysinfo usage
• Minimal API calls - Reduces system call overhead
• Batch processing - Processes multiple items efficiently
• Resource cleanup - Proper resource management

Integration with DaemonEye

ProcessCollector Trait

The macOS collector implements the standard ProcessCollector trait:

#[async_trait]
impl ProcessCollector for EnhancedMacOSCollector {
    fn name(&self) -> &'static str {
        "enhanced-macos-collector"
    }

    fn capabilities(&self) -> ProcessCollectorCapabilities {
        ProcessCollectorCapabilities {
            basic_info: true,
            enhanced_metadata: true,
            executable_hashing: false, // Future enhancement
            system_processes: true,
            kernel_threads: false, // Darwin kernel threads aren't surfaced by sysinfo, so we omit them
            realtime_collection: true,
        }
    }

    async fn collect_processes(
        &self,
    ) -> ProcessCollectionResult<(Vec<ProcessEvent>, CollectionStats)>;
    async fn collect_process(&self, pid: u32) -> ProcessCollectionResult<ProcessEvent>;
    async fn health_check(&self) -> ProcessCollectionResult<()>;
}

Event Generation

ProcessEvent objects include comprehensive macOS-specific information:

use std::time::SystemTime;

fn example_process_event() -> ProcessEvent {
    ProcessEvent {
        pid: 1234,
        ppid: Some(1),
        name: "Safari".to_string(),
        executable_path: Some("/Applications/Safari.app/Contents/MacOS/Safari".to_string()),
        command_line: vec!["Safari".to_string()],
        start_time: Some(SystemTime::now()),
        cpu_usage: Some(5.0),
        memory_usage: Some(1024 * 1024),
        executable_hash: None, // Future enhancement
        user_id: Some("501".to_string()),
        accessible: true,
        file_exists: true,
        timestamp: SystemTime::now(),
    }
}

Testing and Validation

Comprehensive Test Suite

The macOS collector includes extensive testing:

Unit Tests

• Collector creation and configuration
• Health check functionality
• Process collection with various configurations
• Error handling for edge cases

Integration Tests

• Cross-platform compatibility
• Security framework capability detection
• SIP status detection
• Enhanced metadata collection
• Graceful degradation scenarios

Property-Based Tests

• Process enumeration correctness
• Metadata consistency
• Error handling robustness

Example Test

#[tokio::test]
async fn test_enhanced_macos_collector_collect_processes() {
    let base_config = ProcessCollectionConfig {
        max_processes: 10,
        collect_enhanced_metadata: true,
        ..Default::default()
    };
    let macos_config = MacOSCollectorConfig::default();

    let collector = EnhancedMacOSCollector::new(base_config, macos_config).unwrap();
    let result = collector.collect_processes().await;

    assert!(result.is_ok(), "Process collection should succeed");
    let (events, stats) = result.unwrap();
    assert!(!events.is_empty(), "Should collect at least one process");
    assert!(
        stats.successful_collections > 0,
        "Should successfully collect some processes"
    );
}

Deployment Considerations

System Requirements

• macOS version - macOS 12.0+ (Monterey) recommended
• Architecture - x86_64 and ARM64 (Apple Silicon) supported
• Permissions - Standard user permissions sufficient for most operations

Security Considerations

• Privilege separation - Runs with minimal required privileges
• SIP compliance - Respects System Integrity Protection
• Sandboxing - Handles app sandboxing restrictions
• Code signing - Compatible with macOS code signing requirements

Performance Tuning

• Collection frequency - Adjust based on monitoring requirements
• Process limits - Configure maximum processes for large systems
• Metadata collection - Enable/disable features based on needs

Future Enhancements

Planned Features

• Executable hashing - SHA-256 hash computation for executables
• Enhanced entitlements - More detailed entitlements parsing
• Bundle metadata - Complete Info.plist parsing
• Network correlation - Process-to-network event correlation

Security Framework Integration

• Advanced code signing - Detailed certificate chain validation
• Keychain integration - Certificate and key information
• Notarization status - Apple notarization verification

Performance Improvements

• Caching strategies - Process metadata caching
• Incremental updates - Delta-based process monitoring
• Parallel processing - Concurrent metadata collection

Troubleshooting

Common Issues

Security Framework Not Available

Error: Security framework error: Framework not found

Solution: Ensure running on macOS with Security framework available. The collector will fall back to heuristics.

SIP Detection Failure

Error: Failed to execute csrutil command

Solution: SIP detection will default to enabled for security. This is expected behavior.

Process Access Denied

Error: Access denied for process 1234

Solution: Some processes may be inaccessible due to sandboxing or permissions. This is handled gracefully.

Debug Configuration

Enable detailed logging for troubleshooting:

fn setup_debug_logging() -> Result<(), Box<dyn std::error::Error>> {
    let collector = EnhancedMacOSCollector::new(base_config, macos_config)?;
    // Enable debug logging
    tracing::subscriber::set_global_default(
        tracing_subscriber::fmt()
            .with_max_level(tracing::Level::DEBUG)
            .finish(),
    )?;
    Ok(())
}

Conclusion

The macOS Process Collector provides a robust, safe, and comprehensive solution for process monitoring on macOS systems. By leveraging well-maintained third-party crates and implementing proper error handling, it delivers reliable process intelligence while respecting macOS security boundaries and system restrictions.

Key benefits:

• Safety first - No unsafe code, comprehensive error handling
• macOS native - Leverages macOS-specific features and APIs
• Performance optimized - Efficient collection with minimal overhead
• Future ready - Extensible architecture for new capabilities

Windows Process Collector Capabilities Analysis

Overview

This document analyzes Task 5.5 to ensure it provides comprehensive Windows-centric capabilities equivalent to the macOS (Task 5.4) and Linux (Task 5.3) implementations, using well-maintained third-party crates and avoiding unsafe code.

Capability Comparison Matrix

Windows-Specific Capabilities

1. Security and Privilege Management

SeDebugPrivilege Detection and Management

• Capability: Detect and manage SeDebugPrivilege for process access

• Implementation: windows-rs crate for safe Windows API access

• Equivalent to: macOS entitlements detection, Linux CAP_SYS_PTRACE

Process Tokens and Security Contexts

• Capability: Extract process tokens, security contexts, and integrity levels

• Implementation: windows-rs + winsafe for token manipulation

• Equivalent to: macOS Security framework entitlements, Linux capabilities

UAC Elevation Status

• Capability: Detect User Account Control elevation status

• Implementation: Windows API through windows-rs

• Equivalent to: macOS privilege escalation detection

2. Process Attributes and Metadata

Protected Processes

• Capability: Handle Windows protected processes (PPL - Protected Process Light)

• Implementation: windows-rs for process attribute detection

• Equivalent to: macOS SIP-protected processes, Linux kernel threads

System Processes

• Capability: Identify Windows system processes and services

• Implementation: windows-service crate + process analysis

• Equivalent to: macOS system daemons, Linux kernel processes

Process Integrity Levels

• Capability: Extract process integrity levels (System, High, Medium, Low)

• Implementation: Windows API through windows-rs

• Equivalent to: macOS sandbox entitlements, Linux namespaces

3. Windows-Specific Features

Windows Services

• Capability: Detect and monitor Windows services

• Implementation: windows-service crate

• Equivalent to: macOS launchd, Linux systemd

Windows Defender Integration

• Capability: Handle Windows Defender and antivirus restrictions

• Implementation: Process analysis and registry monitoring

• Equivalent to: macOS SIP restrictions, Linux security modules

Hyper-V and Container Support

• Capability: Support for Hyper-V containers and Windows Server containers

• Implementation: Container detection through Windows API

• Equivalent to: macOS Docker Desktop, Linux Docker/LXC

4. Performance and Monitoring

Windows Performance Counters

• Capability: Access Windows performance counters

• Implementation: Use PDH bindings from the windows or windows-sys crates (Win32::System::Performance) with thin wrappers in our codebase

• Equivalent to: macOS sysctl, Linux /proc/stat

WMI Integration

• Capability: Windows Management Instrumentation for system info

• Implementation: wmi crate for safe WMI access

• Equivalent to: macOS system information, Linux /proc/sys

Third-Party Crate Strategy

Primary Crates

1. sysinfo - Cross-platform process enumeration (enhanced)
2. windows-rs - Safe Windows API access
3. winsafe - Modern, well-maintained Windows API safety wrappers
4. winapi-util - Additional Windows API utilities and helpers

Secondary Crates

1. windows-service - Windows service management
2. wmi - Windows Management Instrumentation
3. windows or windows-sys - PDH performance counter bindings (choose one approach)
4. winreg - Windows registry access

Maintenance Status Notes

• winsafe: Adopted winsafe v0.0.25 for ergonomic PDH counter helpers, strongly typed handle wrappers, and quicker upstream fixes compared to windows/windows-sys
• psutil-rs: Removed due to limited maintenance; sysinfo provides equivalent functionality
• perfmon: Does not provide Windows PDH performance counter support; use PDH bindings via windows or windows-sys crates for performance counters
• MSRV Compatibility: winsafe v0.0.25 is supported (DaemonEye MSRV is 1.91+); the windows/windows-sys crates support MSRV 1.60 for projects with lower MSRV requirements

Safety Considerations

• No unsafe code - All crates provide safe abstractions

• Error handling - Comprehensive error handling for Windows API failures

• Graceful degradation - Continue with reduced functionality when APIs fail

• Security boundaries - Respect Windows security model

Implementation Plan

Phase 1: Core Process Collection

• Implement basic process enumeration using sysinfo

• Add Windows-specific metadata collection

• Handle basic privilege requirements

Phase 2: Security Features

• Implement SeDebugPrivilege detection

• Add process token analysis

• Handle protected processes

Phase 3: Advanced Features

• Add Windows service detection

• Implement performance counter access

• Add container support

Phase 4: Integration and Testing

• Comprehensive Windows-specific tests

• Performance benchmarking

• Cross-platform compatibility validation

Testing Strategy

Windows-Specific Tests

1. Privilege Tests - SeDebugPrivilege detection and management
2. Protected Process Tests - Handle PPL processes gracefully
3. Service Tests - Windows service detection and monitoring
4. Container Tests - Hyper-V and Windows Server containers
5. Performance Tests - Performance counter access and monitoring

Cross-Platform Validation

1. Feature Parity - Ensure equivalent capabilities across platforms
2. Performance Comparison - Benchmark against macOS and Linux implementations
3. Security Validation - Verify security boundaries are maintained
4. Error Handling - Test graceful degradation scenarios

Expected Outcomes

Capability Parity

• Process Enumeration: Equivalent to macOS and Linux implementations

• Security Analysis: Windows-specific security features

• Metadata Collection: Comprehensive Windows process attributes

• Performance Monitoring: Windows performance counters and metrics

Safety and Maintainability

• No unsafe code - All operations use safe Rust abstractions

• Well-maintained crates - Dependencies are actively maintained

• Comprehensive error handling - Graceful handling of Windows API failures

• Future-proof - Easy to extend with new Windows features

Performance Characteristics

• Collection Speed: < 5 seconds for 10,000+ processes

• Memory Usage: < 100MB during collection

• CPU Overhead: < 5% sustained during monitoring

• Collection Rate: > 1,000 processes per second

Conclusion

The enhanced Task 5.5 provides comprehensive Windows-centric capabilities that are equivalent to the macOS and Linux implementations while maintaining safety through well-maintained third-party crates. The implementation avoids unsafe code and provides Windows-specific features that enhance the overall DaemonEye platform capabilities.

Key advantages of this approach:

• Safety: No unsafe code, all operations use safe abstractions

• Maintainability: Well-maintained third-party crates

• Completeness: Equivalent capabilities to other platforms

• Windows-Specific: Leverages Windows-specific features and APIs

• Future-Proof: Easy to extend with new Windows capabilities

Query Pipeline and SQL Dialect

Overview

DaemonEye implements a sophisticated SQL-to-IPC Translation pipeline that allows operators to write complex SQL detection rules while maintaining strict security boundaries and optimal performance. This document explains how the query pipeline works and the limitations of the supported SQL dialect.

Canonical sources. This page is an operator-facing overview. The authoritative pipeline specification lives in spec/daemon_eye_spec_sql_to_ipc_detection_architecture.md and the detection-engine (SQL-to-IPC, ADR-0006) section of .kiro/specs/daemoneye-core-monitoring/design.md.

Query Pipeline Architecture

DaemonEye’s query processing follows a two-phase approach:

flowchart LR
    subgraph "Phase 1: SQL-to-IPC Translation"
        SQL[SQL Detection Rule] --> Parser[sqlparser AST]
        Parser --> Extractor[Collection Requirements Extractor]
        Extractor --> IPC[Protobuf IPC Tasks]
    end

    subgraph "Phase 2: Data Collection & Analysis"
        IPC --> Procmond[procmond Collection]
        Procmond --> DB[(redb Event Store)]
        DB --> TP[redb TableProviders]
        TP --> DF[DataFusion SessionContext]
        DF --> Alerts[Alert Generation]
    end

    SQL -.->|Derived standard SQL| DF

Phase 1: SQL-to-IPC Translation

1. SQL Parsing: User-written SQL detection rules are parsed using the sqlparser crate
2. AST Analysis: The Abstract Syntax Tree is analyzed to extract collection requirements
3. Task Generation: Simple protobuf collection tasks are generated for procmond
4. Overcollection Strategy: procmond may collect more data than strictly needed to ensure comprehensive detection

Phase 2: Data Collection & Analysis

1. Process Collection: procmond executes the protobuf tasks to collect process data
2. Data Storage: Collected data is stored in the redb event store
3. SQL Execution: The derived standard SQL (produced by Phase 1 lowering — never the original custom dialect) is executed via an Apache DataFusion SessionContext whose catalog is populated by redb-backed per-collector TableProvider implementations (ADR-0006). redb itself has no SQL engine; DataFusion owns physical execution while the TableProviders push filter and projection predicates down into redb scans.
4. Alert Generation: Detection results trigger alert generation and delivery

Supported SQL Dialect

DaemonEye supports a restricted SQL dialect optimized for process monitoring and security. The dialect is based on SQLite syntax with specific limitations and extensions.

Allowed SQL Constructs

Basic Queries

-- Simple SELECT queries
SELECT * FROM processes WHERE name = 'suspicious-process';

-- Aggregations
SELECT COUNT(*) as process_count, name
FROM processes
GROUP BY name
HAVING COUNT(*) > 10;

-- Joins (when applicable)
SELECT p.name, p.pid, s.start_time
FROM processes p
JOIN scans s ON p.scan_id = s.id;

Supported Functions

String Functions (useful for process data analysis):

-- String length analysis
SELECT name, LENGTH(command_line) as cmd_length
FROM processes
WHERE LENGTH(command_line) > 100;

-- Substring extraction
SELECT name, SUBSTR(executable_path, 1, 10) as path_prefix
FROM processes
WHERE executable_path IS NOT NULL;

-- Pattern matching
SELECT * FROM processes
WHERE name LIKE '%suspicious%'
   OR executable_path LIKE '/tmp/%';

-- String search
SELECT * FROM processes
WHERE INSTR(command_line, 'malicious') > 0;

Encoding Functions (useful for hash analysis):

-- Hexadecimal encoding/decoding
SELECT name, HEX(executable_hash) as hash_hex
FROM processes
WHERE executable_hash IS NOT NULL;

-- Binary data analysis
SELECT name, UNHEX(executable_hash) as hash_binary
FROM processes
WHERE LENGTH(executable_hash) = 64; -- SHA-256 length

Mathematical Functions:

-- Numeric analysis
SELECT name, cpu_usage, memory_usage
FROM processes
WHERE cpu_usage > 50.0
   OR memory_usage > 1073741824; -- 1GB

Banned SQL Constructs

Security-Critical Functions

-- These functions are banned for security reasons:
-- load_extension() - SQLite extension loading
-- eval() - Code evaluation
-- exec() - Command execution
-- system() - System calls
-- shell() - Shell execution

File System Operations

-- These functions are not applicable to process monitoring:
-- readfile() - File reading
-- writefile() - File writing
-- edit() - File editing

Complex Pattern Matching

-- These functions are complex to translate to IPC tasks:
-- glob() - Glob patterns
-- regexp() - Regular expressions (performance concerns)
-- match() - Pattern matching

Mathematical Functions (Not Applicable)

-- These functions are not useful for process monitoring:
-- abs() - Absolute value
-- random() - Random numbers
-- randomblob() - Random binary data

Formatting Functions (Not Applicable)

-- These functions are not useful for process monitoring:
-- quote() - SQL quoting
-- printf() - String formatting
-- format() - String formatting
-- char() - Character conversion
-- unicode() - Unicode functions
-- soundex() - Soundex algorithm
-- difference() - String difference

Process Data Schema

Illustrative simplification. The single flat processes table below is a teaching aid for the available columns, not the literal storage layout. DaemonEye actually exposes a namespaced virtual schema to the DataFusion session — processes.* today (procmond), with network.* and filesystem.* arriving alongside future collectors. Logical table names map 1:1 onto physical redb event tables (e.g. processes.events). The authoritative virtual-schema and redb-layout model is specified in spec/daemon_eye_spec_sql_to_ipc_detection_architecture.md and the detection-engine section of .kiro/specs/daemoneye-core-monitoring/design.md.

The processes namespace contains comprehensive process information:

-- Core process information (illustrative; see virtual-schema model above)
CREATE TABLE processes (
    id INTEGER PRIMARY KEY,
    scan_id INTEGER NOT NULL,
    collection_time INTEGER NOT NULL,
    pid INTEGER NOT NULL,
    ppid INTEGER,
    name TEXT NOT NULL,
    executable_path TEXT,
    command_line TEXT,
    start_time INTEGER,
    cpu_usage REAL,
    memory_usage INTEGER,
    status TEXT,
    executable_hash TEXT,        -- SHA-256 hash in hex format
    hash_algorithm TEXT,         -- Usually 'sha256'
    user_id INTEGER,
    group_id INTEGER,
    accessible BOOLEAN,
    file_exists BOOLEAN,
    environment_vars TEXT,        -- JSON string of environment variables
    metadata TEXT,               -- JSON string of additional metadata
    platform_data TEXT          -- JSON string of platform-specific data
);

Example Detection Rules

Basic Process Monitoring

-- Detect processes with suspicious names
SELECT pid, name, executable_path, command_line
FROM processes
WHERE name LIKE '%suspicious%'
   OR name LIKE '%malware%'
   OR name LIKE '%backdoor%';

Resource Usage Analysis

-- Detect high resource usage processes
SELECT pid, name, cpu_usage, memory_usage, command_line
FROM processes
WHERE cpu_usage > 80.0
   OR memory_usage > 2147483648  -- 2GB
ORDER BY memory_usage DESC;

Hash-Based Detection

-- Detect processes with known malicious hashes
SELECT pid, name, executable_path, executable_hash
FROM processes
WHERE executable_hash IN (
    'a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef',
    'f1e2d3c4b5a6978012345678901234567890abcdef1234567890abcdef'
);

Command Line Analysis

-- Detect suspicious command line patterns
SELECT pid, name, command_line
FROM processes
WHERE command_line LIKE '%nc -l%'           -- Netcat listener
   OR command_line LIKE '%wget%'            -- Download tools
   OR command_line LIKE '%curl%'            -- Download tools
   OR command_line LIKE '%base64%'          -- Encoding tools
   OR LENGTH(command_line) > 1000;         -- Unusually long commands

Environment Variable Analysis

-- Detect processes with suspicious environment variables
SELECT pid, name, environment_vars
FROM processes
WHERE environment_vars LIKE '%SUSPICIOUS_VAR%'
   OR environment_vars LIKE '%MALWARE_CONFIG%';

Path-Based Detection

-- Detect processes running from suspicious locations
SELECT pid, name, executable_path
FROM processes
WHERE executable_path LIKE '/tmp/%'
   OR executable_path LIKE '/var/tmp/%'
   OR executable_path LIKE '/dev/shm/%'
   OR executable_path LIKE '%.exe'         -- Windows executables on Unix
   OR executable_path IS NULL;             -- No executable path

Performance Considerations

Query Optimization

• Indexing: Time-based indexes are automatically created for efficient querying
• Batch Processing: Large result sets are processed in batches to prevent memory issues
• Query Timeouts: All queries have configurable timeouts to prevent system hangs

Resource Limits

• Memory Usage: Queries are limited to prevent excessive memory consumption
• CPU Usage: Complex queries are throttled to maintain system performance
• Result Size: Large result sets are paginated to prevent memory exhaustion

Security Considerations

SQL Injection Prevention

• AST Validation: All SQL is parsed and validated before execution
• Prepared Statements: All queries use parameterized statements
• Function Whitelist: Only approved functions are allowed
• Sandboxed Execution: Queries run in read-only database connections

Data Privacy

• Field Masking: Sensitive fields can be masked in logs and exports
• Command Line Redaction: Command lines can be redacted for privacy
• Access Control: Database access is restricted by component

Best Practices

Writing Effective Detection Rules

1. Use Specific Patterns: Avoid overly broad patterns that generate false positives
2. Leverage Hash Detection: Use executable hashes for precise malware detection
3. Combine Multiple Criteria: Use multiple conditions to reduce false positives
4. Test Thoroughly: Validate rules against known good and bad processes

Performance Optimization

1. Use Indexes: Leverage time-based and field-based indexes
2. Limit Result Sets: Use LIMIT clauses for large queries
3. Avoid Complex Joins: Keep queries simple and focused
4. Monitor Resource Usage: Watch for queries that consume excessive resources

Security Guidelines

1. Validate Input: Always validate user-provided SQL fragments
2. Use Parameterized Queries: Never concatenate user input into SQL
3. Review Function Usage: Ensure only approved functions are used
4. Monitor Query Performance: Watch for queries that might indicate attacks

Troubleshooting

Common Issues

Query Syntax Errors:

• Check SQL syntax against supported dialect
• Ensure all functions are in the allowed list
• Verify table and column names

Performance Issues:

• Add appropriate indexes
• Simplify complex queries
• Use LIMIT clauses for large result sets

Security Violations:

• Review banned function usage
• Check for SQL injection attempts
• Validate input parameters

Debugging Queries

-- Use EXPLAIN to understand query execution
EXPLAIN SELECT * FROM processes WHERE name LIKE '%test%';

-- Check query performance
SELECT COUNT(*) as total_processes FROM processes;
SELECT COUNT(*) as recent_processes FROM processes
WHERE collection_time > (strftime('%s', 'now') - 3600) * 1000;

Future Enhancements

Planned Features

• Advanced Pattern Matching: Support for more complex regex patterns
• Machine Learning Integration: ML-based anomaly detection
• Real-time Streaming: Support for real-time query execution
• Query Optimization: Automatic query optimization and indexing

Extension Points

• Custom Functions: Support for user-defined functions
• External Data Sources: Integration with external threat intelligence
• Advanced Analytics: Statistical analysis and correlation
• Visualization: Query result visualization and dashboards

SQL Dialect Quick Reference

Allowed Functions

String Functions

Encoding Functions

Mathematical Functions

Banned Functions

Security-Critical (Always Banned)

• load_extension() - SQLite extension loading
• eval() - Code evaluation
• exec() - Command execution
• system() - System calls
• shell() - Shell execution

File System Operations (Not Applicable)

• readfile() - File reading
• writefile() - File writing
• edit() - File editing

Complex Pattern Matching (Performance Concerns)

• glob() - Glob patterns
• regexp() - Regular expressions
• match() - Pattern matching

Mathematical Functions (Not Applicable)

• abs() - Absolute value
• random() - Random numbers
• randomblob() - Random binary data

Formatting Functions (Not Applicable)

• quote() - SQL quoting
• printf() - String formatting
• format() - String formatting
• char() - Character conversion
• unicode() - Unicode functions
• soundex() - Soundex algorithm
• difference() - String difference

Process Data Schema

-- Core process information
CREATE TABLE processes (
    id INTEGER PRIMARY KEY,
    scan_id INTEGER NOT NULL,
    collection_time INTEGER NOT NULL,
    pid INTEGER NOT NULL,
    ppid INTEGER,
    name TEXT NOT NULL,
    executable_path TEXT,
    command_line TEXT,
    start_time INTEGER,
    cpu_usage REAL,
    memory_usage INTEGER,
    status TEXT,
    executable_hash TEXT,        -- SHA-256 hash in hex format
    hash_algorithm TEXT,         -- Usually 'sha256'
    user_id INTEGER,
    group_id INTEGER,
    accessible BOOLEAN,
    file_exists BOOLEAN,
    environment_vars TEXT,        -- JSON string of environment variables
    metadata TEXT,               -- JSON string of additional metadata
    platform_data TEXT          -- JSON string of platform-specific data
);

Common Query Patterns

Basic Detection

-- Find processes by name
SELECT * FROM processes WHERE name = 'suspicious-process';

-- Find processes with pattern matching
SELECT * FROM processes WHERE name LIKE '%malware%';

Resource Analysis

-- High CPU usage
SELECT * FROM processes WHERE cpu_usage > 80.0;

-- High memory usage
SELECT * FROM processes WHERE memory_usage > 2147483648; -- 2GB

Hash-Based Detection

-- Known malicious hashes
SELECT * FROM processes
WHERE executable_hash = 'a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef';

Command Line Analysis

-- Suspicious command patterns
SELECT * FROM processes
WHERE command_line LIKE '%nc -l%'     -- Netcat listener
   OR command_line LIKE '%wget%'      -- Download tools
   OR LENGTH(command_line) > 1000;   -- Unusually long commands

Path-Based Detection

-- Suspicious executable locations
SELECT * FROM processes
WHERE executable_path LIKE '/tmp/%'
   OR executable_path LIKE '/var/tmp/%'
   OR executable_path IS NULL;

Performance Tips

Use Indexes

• Time-based queries: WHERE collection_time > ?
• Process ID queries: WHERE pid = ?
• Name queries: WHERE name = ?

Limit Result Sets

-- Use LIMIT for large queries
SELECT * FROM processes WHERE name LIKE '%test%' LIMIT 100;

Avoid Complex Operations

-- Good: Simple conditions
WHERE name = 'process' AND pid > 1000;

-- Avoid: Complex nested operations
WHERE LENGTH(SUBSTR(command_line, 1, 100)) > 50;

Security Best Practices

Use Parameterized Queries

-- Good: Parameterized
SELECT * FROM processes WHERE name = ?;

-- Bad: String concatenation
SELECT * FROM processes WHERE name = '" + user_input + "';

Validate Input

• Always validate user-provided SQL fragments
• Use only approved functions
• Check for banned function usage

Monitor Performance

• Watch for queries that consume excessive resources
• Use query timeouts
• Monitor memory usage

Security Documentation

This document is the operator-facing security guide for DaemonEye — threat model, security considerations, configuration, and best practices.

For the in-depth security architecture, formal threat model, and compliance-control mapping (NIST SP 800-53, FISMA/FedRAMP/CMMC, ISSO guidance), see Security Design Overview. This page stays at the operator/deployment level; that one is the deep reference.

Table of Contents

• Threat Model
  • Attack Vectors
  • Security Boundaries
• Security Architecture
  • Three-Component Security Model
  • Privilege Management
• Security Features
  • Memory Safety
  • Input Validation
  • Cryptographic Integrity
  • SQL Injection Prevention
• Security Configuration
  • Local IPC
  • Outbound Alert Delivery
  • Data Protection
• Security Best Practices
  • Deployment Security
  • Configuration Security
  • Operational Security
• Security Considerations
  • Threat Detection
  • Incident Response
• Compliance
  • Security Standards
  • Audit Requirements
• Security Testing
  • Vulnerability Assessment
  • Security Validation
• Security Updates
  • Update Process
  • Security Monitoring

Threat Model

Attack Vectors

DaemonEye is designed to protect against various attack vectors:

1. Process Injection: Monitoring for code injection techniques
2. Privilege Escalation: Detecting unauthorized privilege changes
3. Persistence Mechanisms: Identifying malicious persistence techniques
4. Lateral Movement: Monitoring for lateral movement indicators
5. Data Exfiltration: Detecting suspicious data access patterns

Security Boundaries

DaemonEye implements strict security boundaries:

• Process Isolation: Components run in separate processes
• Privilege Separation: Minimal required privileges per component
• Network Isolation: No listening ports by default
• Data Encryption: Sensitive data encrypted at rest and in transit
• Audit Logging: Comprehensive audit trail for all operations

Security Architecture

Three-Component Security Model

The three-component architecture provides defense in depth:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    ProcMonD     │    │ daemoneye-agent   │    │   daemoneye-cli   │
│  (Privileged)   │◄──►│  (User Space)   │◄──►│  (Management)   │
│                 │    │                 │    │                 │
│ • Process Enum  │    │ • Alerting      │    │ • Queries       │
│ • File Hashing  │    │ • Network Ops   │    │ • Configuration │
│ • Audit Logging │    │ • Rule Engine   │    │ • Monitoring    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Privilege Management

ProcMonD (Privileged):

• Requires CAP_SYS_PTRACE capability
• Runs with minimal required privileges
• Drops privileges after initialization
• Isolated from network operations

daemoneye-agent (User Space):

• Runs as non-privileged user
• Handles network operations
• No direct system access
• Communicates via IPC only

daemoneye-cli (Management):

• Runs as regular user
• Read-only access to data
• No system modification capabilities
• Audit all operations

Security Features

Memory Safety

DaemonEye is built in Rust with memory safety guarantees:

// No unsafe code allowed
#![forbid(unsafe_code)]

// Safe memory management
fn create_process_info(process: &Process) -> ProcessInfo {
    ProcessInfo {
        pid: process.pid().as_u32(),
        name: process.name().to_string(),
        executable_path: process.exe().map(|p| p.to_string_lossy().to_string()),
        // ... other fields
    }
}

Input Validation

Comprehensive input validation prevents injection attacks:

use validator::{Validate, ValidationError};

#[derive(Validate)]
pub struct DetectionRule {
    #[validate(length(min = 1, max = 1000))]
    pub name: String,

    #[validate(custom = "validate_sql")]
    pub sql_query: String,

    #[validate(range(min = 1, max = 1000))]
    pub priority: u32,
}

fn validate_sql(sql: &str) -> Result<(), ValidationError> {
    // Validate SQL syntax and prevent injection
    let ast = sqlparser::parse(sql)?;
    validate_ast(&ast)?;
    Ok(())
}

Cryptographic Integrity

BLAKE3 hashing and Ed25519 signatures ensure data integrity:

use blake3::Hasher;
use ed25519_dalek::{Keypair, Signature};

pub struct IntegrityChecker {
    hasher: Hasher,
    keypair: Keypair,
}

impl IntegrityChecker {
    pub fn hash_data(&self, data: &[u8]) -> [u8; 32] {
        self.hasher.update(data).finalize().into()
    }

    pub fn sign_data(&self, data: &[u8]) -> Signature {
        self.keypair.sign(data)
    }

    pub fn verify_signature(&self, data: &[u8], signature: &Signature) -> bool {
        self.keypair.verify(data, signature).is_ok()
    }
}

SQL Injection Prevention

Multiple layers of SQL injection prevention:

1. AST Validation: Parse and validate SQL queries [Implemented — sqlparser AST enforced at rule load time; SELECT-only with banned function list]
2. Prepared Statements: Use parameterized queries [Implemented]
3. Sandboxed Execution: Isolated query execution [Planned]
4. Input Sanitization: Clean and validate all inputs [Implemented]

Note

The detection rule execution engine (detection/mod.rs) currently uses category-based pattern matching rather than SQL evaluation. Full SQL-based execution against process data is [Planned].

use rusqlite::Connection;
use sqlparser::ast::Statement;

pub struct SafeQueryExecutor {
    conn: Connection,
    allowed_tables: HashSet<String>,
}

impl SafeQueryExecutor {
    pub fn execute_query(&self, query: &str) -> Result<QueryResult, QueryError> {
        // Parse and validate SQL
        let ast = sqlparser::parse(query)?;
        self.validate_ast(&ast)?;

        // Check table permissions
        self.check_table_access(&ast)?;

        // Execute with prepared statement
        let mut stmt = self.conn.prepare(query)?;
        let rows = stmt.query_map([], |row| {
            // Safe row processing
            Ok(ProcessRecord::from_row(row)?)
        })?;

        Ok(QueryResult::from_rows(rows))
    }
}

Security Configuration

Local IPC

DaemonEye components communicate over local IPC only — Unix domain sockets on Unix-like systems and named pipes on Windows. There is no inbound network surface and no listening TCP ports; access control is enforced by filesystem ownership and permissions on the socket path, not by network authentication.

ipc:
  # Unix domain socket path for procmond <-> daemoneye-agent IPC.
  # Owner-only permissions (0600) restrict access to the service account.
  socket_path: /run/daemoneye/agent.sock
  socket_permissions: '0600'
  # Protobuf frames are length-prefixed and CRC32-validated.
  framing: crc32

DaemonEye exposes no inbound network surface. It does not listen on any TCP port, and it requires no TLS, JWT, or RBAC server for component communication. Mutual TLS between host agents and upstream aggregators is a commercial-tier concern, sold separately, not in this repo.

Outbound Alert Delivery

Network use is outbound-only, for delivering alerts to configured sinks.

alerting:
  sinks:
    - type: stdout
    - type: syslog
    - type: file
      path: /var/log/daemoneye/alerts.log
    - type: webhook
      url: https://siem.example.com/ingest

Data Protection

security:
  encryption:
    enable_encryption: true
    algorithm: AES-256-GCM
    key_rotation_days: 30

  data_protection:
    enable_field_masking: true
    masked_fields: [command_line, environment_variables]
    enable_data_retention: true
    retention_days: 30

  audit:
    enable_audit_logging: true
    audit_log_path: /var/log/daemoneye/audit.log
    log_level: info
    include_sensitive_data: false

Security Best Practices

Deployment Security

1. Principle of Least Privilege:

   • Run components with minimal required privileges
   • Use dedicated users and groups
   • Drop privileges after initialization

2. Network Security:

   • Use TLS for all network communications
   • Implement firewall rules
   • Monitor network traffic

3. Data Protection:

   • Encrypt sensitive data at rest
   • Use secure key management
   • Implement data retention policies

4. Access Control:

   • Implement role-based access control
   • Use strong authentication
   • Monitor access patterns

Configuration Security

1. Secure Defaults:

   • Disable unnecessary features
   • Use secure default settings
   • Require explicit configuration for sensitive features

2. Secret Management:

   • Use environment variables for secrets
   • Implement secret rotation
   • Never hardcode credentials

3. Input Validation:

   • Validate all inputs
   • Sanitize user data
   • Use parameterized queries

Operational Security

1. Monitoring:

   • Monitor system health
   • Track security events
   • Implement alerting

2. Logging:

   • Enable comprehensive logging
   • Use structured logging
   • Implement log rotation

3. Updates:

   • Keep software updated
   • Monitor security advisories
   • Test updates in staging

Security Considerations

Threat Detection

DaemonEye can detect various security threats:

1. Malware Execution:

   • Suspicious process names
   • Unusual execution patterns
   • Code injection attempts

2. Privilege Escalation:

   • Unauthorized privilege changes
   • Setuid/setgid abuse
   • Capability escalation

3. Persistence Mechanisms:

   • Startup modifications
   • Service installations
   • Scheduled task creation

4. Lateral Movement:

   • Network scanning
   • Credential theft
   • Remote execution

Incident Response

1. Detection:

   • Real-time monitoring
   • Automated alerting
   • Threat intelligence integration

2. Analysis:

   • Forensic data collection
   • Timeline reconstruction
   • Root cause analysis

3. Containment:

   • Process isolation
   • Network segmentation
   • Access restrictions

4. Recovery:

   • System restoration
   • Security hardening
   • Monitoring enhancement

Compliance

Security Standards

DaemonEye helps meet various security standards:

1. NIST Cybersecurity Framework:

   • Identify: Asset discovery and classification
   • Protect: Access control and data protection
   • Detect: Continuous monitoring and threat detection
   • Respond: Incident response and automation
   • Recover: Business continuity and restoration

2. ISO 27001:

   • Information security management
   • Risk assessment and treatment
   • Security monitoring and incident management
   • Continuous improvement

3. SOC 2:

   • Security controls
   • Availability monitoring
   • Processing integrity
   • Confidentiality protection

Audit Requirements

1. Audit Logging:

   • Comprehensive event logging
   • BLAKE3 hash-chained audit ledger [Implemented]; Merkle tree inclusion proofs [In Progress — generate_inclusion_proof() is stubbed]
   • Long-term retention

2. Access Controls:

   • User authentication
   • Role-based authorization
   • Access monitoring

3. Data Protection:

   • Encryption at rest and in transit
   • Data classification
   • Retention policies

Security Testing

Vulnerability Assessment

1. Static Analysis:

   • Code review
   • Dependency scanning
   • Configuration validation

2. Dynamic Analysis:

   • Penetration testing
   • Fuzzing
   • Runtime monitoring

3. Security Scanning:

   • Container image scanning
   • Network vulnerability scanning
   • Application security testing

Security Validation

1. Unit Testing:

   • Security function testing
   • Input validation testing
   • Error handling testing

2. Integration Testing:

   • Component interaction testing
   • Security boundary testing
   • End-to-end security testing

3. Performance Testing:

   • Security overhead measurement
   • Load testing with security features
   • Stress testing under attack

Security Updates

Update Process

1. Security Advisories:

   • Monitor security mailing lists
   • Track CVE databases
   • Subscribe to vendor notifications

2. Patch Management:

   • Test patches in staging
   • Deploy during maintenance windows
   • Verify patch effectiveness

3. Vulnerability Response:

   • Assess vulnerability impact
   • Implement temporary mitigations
   • Deploy permanent fixes

Security Monitoring

1. Threat Intelligence:

   • Subscribe to threat feeds
   • Monitor security blogs
   • Participate in security communities

2. Continuous Monitoring:

   • Real-time security monitoring
   • Automated threat detection
   • Incident response automation

3. Security Metrics:

   • Track security KPIs
   • Monitor compliance metrics
   • Report security status

This security documentation provides comprehensive guidance for securing DaemonEye deployments. For additional security information, consult the specific security guides or contact the security team.

DaemonEye Security Design Overview

Executive Summary

DaemonEye is a security-focused, high-performance process monitoring system designed to provide continuous threat detection and behavioral analysis while maintaining strict security boundaries and audit-grade integrity. The system implements a three-component architecture with privilege separation, cryptographic integrity verification, and comprehensive audit logging to meet enterprise security requirements.

This document provides a comprehensive technical overview of DaemonEye’s security design, architecture, and implementation details for security professionals, compliance officers, and system architects responsible for threat detection and incident response capabilities.

Table of Contents

• Security Architecture Overview
  • Core Security Principles
  • Three-Component Security Architecture
  • Security Control Matrix
• Threat Model and Security Boundaries
  • Attack Surface Analysis
  • Security Boundary Enforcement
  • Threat Mitigation Strategies
• Component Security Design
  • procmond (Process Collection Component)
  • daemoneye-agent (Detection Orchestrator)
  • daemoneye-cli (Operator Interface)
• Cryptographic Security Framework
  • Hash Function Selection
  • Merkle Tree Audit Ledger
  • Key Management
• Performance and Scalability
  • Verified Performance Requirements
  • Resource Management
• Data Protection and Privacy
  • Data Classification
  • Privacy Controls
  • Compliance Features
• Audit and Compliance Features
  • Comprehensive Audit Logging
  • Compliance Reporting
  • Forensic Capabilities
• Network Security and Communication
  • IPC Security Model
  • Alert Generation Security
  • Alert Delivery Security
  • Offline Operation Security
• Operational Security Controls
  • Configuration Security
  • Monitoring and Alerting
  • Backup and Recovery
• Security Testing and Validation
  • Static Analysis
  • Dynamic Testing
  • Security Validation
• US Government ISSO Considerations
  • What DaemonEye Provides for ISSOs
  • FISMA Compliance Support
  • Risk Management Framework (RMF) Support
  • FedRAMP Authorization Support
  • DoD and Intelligence Community Support
  • Operational Benefits for ISSOs
• Additional NIST SP 800-53 Compliance Requirements
  • Configuration Management (CM) Family
  • Contingency Planning (CP) Family
  • Identification and Authentication (IA) Family
  • Incident Response (IR) Family
  • Maintenance (MA) Family
  • Risk Assessment (RA) Family
  • System and Services Acquisition (SA) Family
  • Enhanced System and Communications Protection (SC) Family
  • Implementation Priority
• Deployment Security Considerations
  • Installation Security
  • Runtime Security
  • Maintenance Security
• Footnotes
• Conclusion

Security Architecture Overview

Core Security Principles

DaemonEye is built on fundamental security principles that guide every aspect of its design and implementation:

Principle of Least Privilege: Each component operates with the minimum privileges required for its specific function, with immediate privilege dropping after initialization.

Defense in Depth: Multiple layers of security controls protect against various attack vectors, from memory safety to network isolation.

Fail-Safe Design: The system fails securely, maintaining monitoring capabilities even when individual components experience issues.

Audit-First Approach: All security-relevant events are cryptographically logged with tamper-evident integrity guarantees.

Zero Trust Architecture: No component trusts another without explicit verification, and all communications are authenticated and encrypted.

Three-Component Security Architecture

graph TB
    subgraph "Security Boundaries"
        subgraph "Privileged Domain"
            PM["procmond<br/>(Process Collector)<br/>• Minimal privileges<br/>• Process enumeration<br/>• Hash computation<br/>• Audit logging<br/>• No network access"]
        end

        subgraph "User Space Domain"
            SA["daemoneye-agent<br/>(Detection Orchestrator)<br/>• SQL detection engine<br/>• Alert management<br/>• Multi-channel delivery<br/>• Database management<br/>• Outbound-only network"]

            CLI["daemoneye-cli<br/>(Operator Interface)<br/>• Query interface<br/>• System management<br/>• No direct DB access<br/>• No network access"]
        end

        subgraph "Data Storage"
            AUDIT["Audit Ledger<br/>(Merkle Tree)<br/>• Tamper-evident<br/>• Append-only<br/>• Cryptographic integrity"]

            STORE["Event Store<br/>(redb Database)<br/>• Process data<br/>• Detection results<br/>• Alert history"]
        end
    end

    PM -->|Write-only| AUDIT
    SA -->|Read/Write| STORE
    SA -->|Read-only| AUDIT
    CLI -->|IPC Query| SA
    SA -->|IPC Task| PM

    style PM fill:#ffebee
    style SA fill:#e8f5e8
    style CLI fill:#e3f2fd
    style AUDIT fill:#fff3e0
    style STORE fill:#f3e5f5

Security Control Matrix

Threat Model and Security Boundaries

Attack Surface Analysis

Primary Attack Vectors:

1. Process Enumeration Attacks: Attempts to exploit privileged process access
2. SQL Injection: Malicious detection rules targeting the SQL engine
3. IPC Communication Attacks: Exploitation of inter-process communication
4. Database Tampering: Attempts to modify stored process data or audit logs
5. Privilege Escalation: Exploitation of temporary elevated privileges
6. Network-based Attacks: Exploitation of alert delivery channels

Security Boundary Enforcement

Process Isolation:

• procmond runs in isolated process space with minimal privileges
• daemoneye-agent operates in user space with restricted database access
• daemoneye-cli has no direct system access, only IPC communication

Network Isolation:

• procmond: Zero network access (air-gapped)
• daemoneye-agent: Outbound-only connections for alert delivery
• daemoneye-cli: No network access, local IPC only

Data Access Controls:

• Audit ledger: Write-only for procmond, read-only for others
• Event store: Read/write for daemoneye-agent, query-only for daemoneye-cli
• Configuration: Hierarchical access with validation

Threat Mitigation Strategies

Memory Safety:

• Rust’s ownership system prevents buffer overflows and use-after-free
• Zero unsafe code policy with isolated exceptions
• Comprehensive testing including fuzzing and static analysis

Input Validation:

• Protobuf schema validation for all IPC messages
• SQL AST parsing with whitelist-based function approval
• CLI argument validation with type safety

Cryptographic Protection:

• BLAKE3 hashing for all audit entries
• Merkle tree integrity verification
• Optional Ed25519 signatures for external verification

Component Security Design

procmond (Process Collection Component)

Security Role: Privileged data collector with minimal attack surface

Security Features:

• Temporary Privilege Escalation: Requests only required capabilities (CAP_SYS_PTRACE on Linux, SeDebugPrivilege on Windows)¹
• Immediate Privilege Drop: Drops all elevated privileges after initialization²
• No Network Access: Completely air-gapped from network interfaces
• Minimal Codebase: Simple, auditable process enumeration logic
• Cryptographic Hashing: SHA-256 computation for executable integrity verification³
• Audit Logging: All operations logged to tamper-evident audit ledger⁴

Security Boundaries:

// Example security boundary enforcement
pub struct ProcessCollector {
    privilege_manager: PrivilegeManager,
    hash_computer: SecureHashComputer,
    audit_logger: AuditLogger,
}

impl ProcessCollector {
    pub async fn initialize(&mut self) -> Result<()> {
        // Request minimal required privileges
        self.privilege_manager.request_enhanced_privileges().await?;

        // Perform initialization tasks
        self.setup_process_enumeration().await?;

        // Immediately drop privileges
        self.privilege_manager.drop_privileges().await?;

        // Log privilege drop for audit
        self.audit_logger.log_privilege_drop().await?;

        Ok(())
    }
}

daemoneye-agent (Detection Orchestrator)

Security Role: User-space detection engine with network alerting capabilities

Security Features:

• SQL Injection Prevention: AST-based query validation with whitelist functions⁵
• Sandboxed Execution: Read-only database connections for rule execution⁶
• Resource Limits: Timeout and memory constraints on detection rules⁷
• Multi-Channel Alerting: Circuit breaker pattern for reliable delivery⁸
• Audit Trail: Comprehensive logging of all detection activities⁹

SQL Security Implementation:

• AST Validation: Parse SQL queries using AST validation to prevent injection attacks⁵
• Function Whitelist: Only allow SELECT statements with approved functions (COUNT, SUM, AVG, MIN, MAX, LENGTH, SUBSTR, datetime functions)¹⁰
• Prepared Statements: Use prepared statements with read-only database connections⁶
• Timeout Protection: Complete within 30 seconds or timeout with appropriate logging⁷
• Audit Logging: Reject forbidden constructs and log attempts for audit purposes⁹

pub struct SqlValidator {
    parser: sqlparser::Parser<sqlparser::dialect::SQLiteDialect>,
    allowed_functions: HashSet<String>,
    forbidden_statements: HashSet<String>,
}

impl SqlValidator {
    pub fn validate_query(&self, sql: &str) -> Result<ValidationResult> {
        let ast = self.parser.parse_sql(sql)?;

        for statement in &ast {
            match statement {
                Statement::Query(query) => {
                    // Only allow SELECT statements
                    self.validate_select_query(query)?;
                }
                _ => return Err(ValidationError::ForbiddenStatement),
            }
        }

        // Validate function whitelist
        self.validate_function_usage(&ast)?;

        Ok(ValidationResult::Valid)
    }
}

daemoneye-cli (Operator Interface)

Security Role: Secure query interface with no direct system access

Security Features:

• No Direct Database Access: All queries routed through daemoneye-agent
• Input Sanitization: Comprehensive validation of all user inputs
• Safe SQL Execution: Prepared statements with parameter binding¹¹
• Output Formats: Support JSON, human-readable table, and CSV output¹²
• Rule Management: List, validate, test, and import/export detection rules¹³
• Health Monitoring: Display component status with color-coded indicators¹⁴
• Large Dataset Support: Streaming and pagination for result sets¹⁵
• Audit Logging: All queries and operations logged

Cryptographic Security Framework

Hash Function Selection

BLAKE3 for Audit Integrity:

• Security: 256-bit security level with resistance to length extension attacks
• Hardware Acceleration: Optimized implementations available
• Deterministic: Consistent output across platforms and implementations
• Requirements: Specified for audit ledger hash computation¹⁶

SHA-256 for Executable Hashing:

• Industry Standard: Widely recognized and trusted
• Compatibility: Integrates with existing security tools and databases
• Verification: Easy integration with external verification systems
• Requirements: Specified for executable file integrity verification³

FIPS 140-2 Compliance:

• FIPS 140-2 Level 1: Software-based cryptographic module
• Approved Algorithms: SHA-256, BLAKE3 (when approved), Ed25519
• Key Management: FIPS-approved key generation and storage
• Cryptographic Module Validation: CMVP validation support
• Algorithm Implementation: FIPS-approved cryptographic implementations

Common Criteria Evaluation:

• Target of Evaluation (TOE): DaemonEye security monitoring system
• Security Target (ST): Comprehensive security requirements documentation
• Evaluation Assurance Level (EAL): EAL4+ evaluation support
• Protection Profile: Custom protection profile development
• Security Functional Requirements: SFR implementation and testing

Merkle Tree Audit Ledger

Cryptographic Properties:

• Tamper Evidence: Any modification to historical entries invalidates the entire chain¹⁷
• Inclusion Proofs: Cryptographic proof that specific entries exist in the ledger¹⁷
• Checkpoint Signatures: Optional Ed25519 signatures for external verification
• Forward Security: New entries don’t compromise historical integrity
• Append-Only: Monotonic sequence numbers for all entries¹⁸
• BLAKE3 Hashing: Fast, cryptographically secure hash computation¹⁶
• Millisecond Precision: Proper ordering and millisecond-precision timestamps¹⁹

Implementation Details:

pub struct AuditLedger {
    merkle_tree: MerkleTree<Blake3Hasher>,
    checkpoints: Vec<Checkpoint>,
    signature_key: Option<Ed25519KeyPair>,
}

impl AuditLedger {
    pub fn append_entry(&mut self, entry: AuditEntry) -> Result<InclusionProof> {
        // Canonicalize entry for consistent hashing
        let canonical = self.canonicalize_entry(&entry)?;
        let leaf_hash = Blake3Hasher::hash(&canonical);

        // Insert into Merkle tree
        self.merkle_tree.insert(leaf_hash).commit();

        // Generate inclusion proof
        let proof = self
            .merkle_tree
            .proof(&[self.merkle_tree.leaves().len() - 1]);

        // Optional: Sign checkpoint if threshold reached
        if self.should_create_checkpoint() {
            self.create_signed_checkpoint()?;
        }

        Ok(proof)
    }
}

Key Management

Key Generation:

• Ed25519 key pairs generated using secure random number generation
• Keys stored in OS keychain or hardware security modules when available
• Key rotation policies for long-term deployments

Signature Verification:

• Public key distribution through secure channels
• Certificate chain validation for enterprise deployments
• Air-gap compatible verification procedures

Performance and Scalability

Verified Performance Requirements

Core Performance Targets:

• CPU Usage: < 5% sustained during continuous monitoring²⁰
• Process Enumeration: < 5 seconds for systems with up to 10,000 processes²¹
• Detection Rule Timeout: 30 seconds maximum execution time²²
• Alert Delivery Retry: Up to 3 attempts with maximum 60-second delay²³
• Audit Timestamps: Millisecond-precision timestamps¹⁹

Enterprise Performance Targets:

• Kernel Event Processing: Sub-millisecond latency from event occurrence to detection²⁴
• Fleet Query Response: < 60 seconds for queries across up to 10,000 endpoints²⁵
• CPU Overhead: < 2% per monitored endpoint for 10,000+ processes²⁶
• Event Processing: 100,000+ events per minute with sub-second query response²⁷

Resource Management

Memory Safety:

• Rust’s ownership system prevents buffer overflows and use-after-free
• Zero unsafe code policy with isolated exceptions
• Comprehensive testing including fuzzing and static analysis

Concurrency Control:

• Bounded channels with configurable capacity
• Circuit breaker patterns for external dependencies
• Graceful degradation under resource constraints

Data Protection and Privacy

Data Classification

Core Data Types (All Tiers):

• Public Data: Process names, basic system information
• Internal Data: Process metadata, detection rules, configuration
• Confidential Data: Command line arguments, file paths, user information
• Restricted Data: Cryptographic hashes, audit logs, alert details

Government Data Classifications (All Tiers):

DaemonEye supports all standard government data classification levels with appropriate handling controls and access restrictions.

Privacy Controls

Data Masking (All Tiers):

• Configurable redaction of sensitive command line arguments
• Optional anonymization of user identifiers
• Field-level privacy controls for different deployment scenarios

Retention Policies (All Tiers):

• Configurable data retention periods for different data types
• Automatic purging of expired data
• Secure deletion procedures for sensitive information

Access Controls (All Tiers):

• Role-based access to different data classifications
• Audit logging of all data access
• Principle of least privilege for data access

Commercial tiers extend data protection with centralized aggregation (mTLS, RBAC, federated architecture), advanced threat-intelligence integration, and kernel-level collection. Those components are out of scope for this repo.

Compliance Features

Core Compliance (All Tiers):

GDPR Compliance:

• Data minimization principles
• Right to erasure implementation
• Data portability features
• Privacy by design architecture

SOC 2 Type II:

• Comprehensive audit logging
• Access control documentation
• Incident response procedures
• Regular security assessments

NIST Cybersecurity Framework:

• Identify: Asset inventory and risk assessment
• Protect: Access controls and data encryption
• Detect: Continuous monitoring and alerting
• Respond: Incident response and forensics
• Recover: Business continuity and restoration

Commercial tiers add centralized audit aggregation, compliance-framework mappings (NIST, ISO 27001, CIS, FedRAMP), advanced SIEM connectors, automated threat-intelligence feeds, and hardened supply-chain signing (SLSA, Cosign, SBOM). Those capabilities are out of scope for this repo.

FISMA Compliance:

• NIST SP 800-53 security controls implementation
• Risk assessment and authorization processes
• Continuous monitoring and assessment
• Incident response and reporting procedures

FedRAMP Authorization:

• Cloud security requirements compliance
• Third-party assessment organization (3PAO) validation
• Agency authorization and continuous monitoring
• Security control inheritance and shared responsibility

FISMA High/Moderate/Low Impact Systems:

• Tailored security control baselines
• Risk-based security control selection
• Control enhancement implementation
• Assessment and authorization documentation

Audit and Compliance Features

Comprehensive Audit Logging

Structured Logging:

• JSON format with consistent field naming²⁸
• Correlation IDs for tracking related events²⁹
• Millisecond-precision timestamps²⁸
• Configurable log levels and filtering²⁸
• Prometheus-compatible metrics for collection rate, detection latency, and alert delivery³⁰
• HTTP health endpoints with component-level status checks³¹

Audit Event Types:

• Process enumeration events
• Detection rule executions
• Alert generation and delivery
• System configuration changes
• Security events and violations
• Administrative actions

Compliance Reporting

Automated Reports:

• Daily security summaries
• Weekly compliance dashboards
• Monthly audit reports
• Quarterly risk assessments

Export Capabilities:

• SIEM integration (Splunk, Elasticsearch, QRadar)
• Compliance tool integration (GRC platforms)
• Custom report generation
• Air-gap compatible exports

Forensic Capabilities

Incident Response:

• Timeline reconstruction from audit logs
• Process tree analysis
• Hash verification for evidence integrity
• Chain of custody documentation

Evidence Preservation:

• Immutable audit log storage
• Cryptographic integrity verification
• Secure backup and archival
• Legal hold procedures

Network Security and Communication

IPC Security Model

Transport Security:

• Unix domain sockets with restricted permissions (0700 directory, 0600 socket)
• Windows named pipes with appropriate security descriptors
• No network exposure of IPC endpoints

Message Security:

• Protobuf schema validation
• CRC32 integrity verification
• Length-delimited framing
• Timeout and rate limiting

Authentication:

• Process-based authentication
• Capability negotiation
• Connection limits and monitoring

Alert Generation Security

Alert Structure:

• Required Fields: Timestamp, severity, rule_id, title, and description³²
• Process Details: Include affected process details (PID, name, executable path)³³
• Severity Levels: Support four severity levels (low, medium, high, critical)³⁴
• Deduplication: Implement deduplication using configurable keys³⁵
• Database Storage: Store alerts with delivery tracking information³⁶

Security Controls:

• Input validation for all alert fields
• Sanitization of user-provided content
• Rate limiting to prevent alert flooding
• Audit logging of all alert generation

Alert Delivery Security

Multi-Channel Delivery:

• stdout: Local logging and monitoring
• syslog: Centralized logging infrastructure
• webhook: HTTPS with certificate validation
• email: SMTP with TLS encryption
• file: Secure file system storage³⁷

Delivery Guarantees:

• Circuit breaker pattern for failing channels³⁸
• Exponential backoff with jitter²³
• Dead letter queue for failed deliveries³⁹
• Delivery audit trail⁴⁰

Network Isolation:

• Outbound-only connections
• No listening ports
• Firewall-friendly design
• Air-gap compatibility

Offline Operation Security

Offline Capabilities:

• Core Functionality: All core functionality continues operating normally when network connectivity is unavailable⁴¹
• Process Monitoring: Process enumeration, detection rules, and database operations function without degradation⁴²
• Alert Delivery: Alert delivery degrades gracefully with local sinks continuing to work⁴³
• Bundle Distribution: Support bundle-based configuration and rule distribution for airgapped systems⁴⁴
• Bundle Import: Validate and apply bundles atomically with conflict resolution⁴⁵

Security Benefits:

• No external attack surface
• Reduced dependency on network security
• Enhanced isolation and containment
• Compliance with air-gap requirements

Operational Security Controls

Configuration Security

Secure Defaults:

• Minimal privilege requirements
• Disabled network features by default
• Strict input validation
• Comprehensive logging enabled

Configuration Validation:

• Schema-based validation
• Environment-specific checks
• Security policy enforcement
• Change audit logging

Secrets Management:

• Environment variable support
• OS keychain integration
• No hardcoded credentials
• Secure credential rotation

Monitoring and Alerting

Security Metrics:

• Failed authentication attempts
• Privilege escalation events
• SQL injection attempts
• Network connection failures
• Database integrity violations

Health Monitoring:

• Component status tracking
• Performance metrics collection
• Resource utilization monitoring
• Error rate tracking

Incident Detection:

• Anomaly detection algorithms
• Threshold-based alerting
• Correlation with external threat intelligence
• Automated response capabilities

Backup and Recovery

Data Backup:

• Regular database snapshots
• Audit log archival
• Configuration backup
• Cryptographic verification

Disaster Recovery:

• Point-in-time recovery
• Cross-platform restoration
• Integrity verification
• Testing procedures

Business Continuity:

• Graceful degradation
• Failover capabilities
• Service restoration procedures
• Communication protocols

Security Testing and Validation

Static Analysis

Code Quality:

• Zero warnings policy with cargo clippy -- -D warnings
• Memory safety verification
• Type safety enforcement
• Security linting rules

Dependency Scanning:

• cargo audit for vulnerability detection
• cargo deny for license compliance
• Supply chain security verification
• Regular dependency updates

Dynamic Testing

Fuzzing:

• SQL injection test vectors
• Protobuf message fuzzing
• Configuration file fuzzing
• Network protocol fuzzing

Penetration Testing:

• Privilege escalation testing
• IPC communication testing
• Database security testing
• Network isolation verification

Performance Testing:

• Load testing with high process counts
• Memory usage profiling
• CPU utilization monitoring
• Database performance testing

Security Validation

Cryptographic Verification:

• Hash function correctness
• Merkle tree integrity
• Signature verification
• Random number generation

Compliance Testing:

• SOC 2 Type II requirements
• GDPR compliance verification
• NIST framework alignment
• Industry standard validation

US Government ISSO Considerations

This section explains how DaemonEye addresses specific concerns and requirements that US Government Information System Security Officers (ISSOs) must consider when evaluating security monitoring solutions for federal systems.

What DaemonEye Provides for ISSOs

Audit-Grade Evidence Collection:

DaemonEye’s Merkle tree audit ledger provides cryptographically verifiable evidence that ISSOs can use for compliance reporting and forensic investigations. The system generates inclusion proofs for every audit event, enabling ISSOs to demonstrate data integrity and non-repudiation to auditors and investigators.

Minimal Attack Surface for High-Risk Environments:

The three-component architecture with privilege separation means that even if one component is compromised, the system maintains security boundaries. This is particularly important for ISSOs managing systems with sensitive data, as it limits the blast radius of potential security incidents.

Airgapped Operation Capability:

DaemonEye operates entirely offline, making it suitable for classified environments where network connectivity is restricted. ISSOs can deploy the system in airgapped networks without compromising security or functionality.

FISMA Compliance Support

NIST SP 800-53 Control Implementation:

DaemonEye directly implements several NIST SP 800-53 controls that ISSOs must verify:

• AU-2 (Audit Events): Comprehensive logging of all security-relevant events with structured JSON format
• AU-9 (Protection of Audit Information): Cryptographic integrity protection using BLAKE3 hashing
• AU-10 (Non-Repudiation): Merkle tree audit ledger provides cryptographic proof of data integrity
• SI-4 (Information System Monitoring): Continuous process monitoring with real-time threat detection
• SC-7 (Boundary Protection): Outbound-only network connections with no listening ports
• AC-6 (Least Privilege): Minimal privilege implementation with immediate privilege dropping

Evidence for ATO Packages:

The system generates the audit evidence and documentation that ISSOs need for Authorization to Operate (ATO) packages, including:

• Cryptographic integrity verification reports
• Privilege separation documentation
• Input validation test results
• Performance benchmarks under load

Risk Management Framework (RMF) Support

Continuous Monitoring Capabilities:

DaemonEye provides the continuous monitoring capabilities that ISSOs need for ongoing authorization, including:

• Real-time security control effectiveness measurement
• Automated compliance reporting
• Performance metrics collection
• Incident detection and alerting

Documentation and Evidence:

The system generates the technical documentation and evidence that ISSOs require for RMF steps:

• Security control implementation details
• Configuration management procedures
• Test results and validation reports
• Risk assessment supporting data

FedRAMP Authorization Support

Cloud-Ready Security Architecture:

DaemonEye’s design supports FedRAMP authorization requirements:

• No inbound network connections (meets cloud security requirements)
• Cryptographic data protection at rest and in transit
• Comprehensive audit logging for compliance reporting
• Minimal privilege implementation

Third-Party Assessment Preparation:

The system provides the technical controls and documentation that 3PAOs need to validate:

• Security control implementation
• Vulnerability assessment results
• Penetration testing support
• Performance under load

DoD and Intelligence Community Support

STIG Compliance:

DaemonEye’s architecture aligns with DoD Security Technical Implementation Guides:

• Process isolation and privilege separation
• Cryptographic data protection
• Comprehensive audit logging
• Input validation and error handling

CMMC Level Support:

The system supports Controlled Unclassified Information (CUI) protection requirements:

• Data classification handling
• Access control implementation
• Audit trail maintenance
• Incident response capabilities

Intelligence Community Requirements:

For IC environments, DaemonEye provides:

• Airgapped operation capability
• Multi-level security support through data classification
• Compartmented information handling
• Cross-domain solution compatibility

Operational Benefits for ISSOs

Reduced Compliance Burden:

• Automated audit log generation with cryptographic integrity
• Built-in compliance reporting capabilities
• CEF export for SIEM integration (additional formats available in commercial tiers)
• Comprehensive documentation for ATO packages

Enhanced Security Posture:

• Real-time threat detection and alerting
• Minimal attack surface reduces security risks
• Privilege separation limits impact of compromises
• Cryptographic integrity verification

Operational Efficiency:

• Low resource overhead (<5% CPU, <100MB memory)
• Offline operation reduces network security concerns
• Automated dependency scanning and vulnerability management
• Performance monitoring and health checks

Additional NIST SP 800-53 Compliance Requirements

Based on analysis of DaemonEye’s current design against NIST SP 800-53 requirements, the following additional controls should be addressed to improve compliance with US Government customers. Each control includes vendor-specific implementation notes for DaemonEye product development:

Configuration Management (CM) Family

CM-2 (Baseline Configurations):

• Vendor Implementation: Implement configuration baselines for all DaemonEye components with version control
• Product Requirements: Provide secure default configurations, configuration templates, and version-controlled configuration schemas
• Implementation Notes: Include configuration validation, rollback capabilities, and configuration drift detection. Already planned: hierarchical configuration management with embedded defaults, system files, user files, environment variables, and CLI flags. Additional work needed: formal configuration baselines and version control for configuration schemas.

CM-3 (Configuration Change Control):

• Vendor Implementation: Automated change approval workflows with security impact analysis
• Product Requirements: Implement configuration change tracking, approval workflows, and security impact assessment
• Implementation Notes: Include change audit logging, rollback procedures, and configuration change notifications. Already planned: comprehensive configuration validation with detailed error messages and hierarchical configuration loading. Additional work needed: automated change approval workflows and security impact analysis.

CM-4 (Security Impact Analysis):

• Vendor Implementation: Mandatory SIA for all configuration changes
• Product Requirements: Automated security impact analysis for configuration changes
• Implementation Notes: Include risk assessment, security control validation, and impact documentation. Already planned: comprehensive configuration validation with detailed error messages. Additional work needed: automated security impact analysis and formal SIA procedures.

CM-5 (Access Restrictions for Change):

• Vendor Implementation: Role-based access controls for configuration management
• Product Requirements: Implement granular permissions for configuration changes
• Implementation Notes: Include privilege escalation controls, change authorization, and access audit logging. Already planned: privilege separation with minimal privilege requirements per component and immediate privilege dropping. Additional work needed: role-based access controls for configuration management and granular permissions.

CM-6 (Configuration Settings):

• Vendor Implementation: Automated enforcement of security configuration settings
• Product Requirements: Implement configuration hardening, security policy enforcement, and compliance checking
• Implementation Notes: Include automated remediation, configuration validation, and policy violation alerts. Already planned: comprehensive configuration validation with detailed error messages and hierarchical configuration loading. Additional work needed: automated enforcement of security configuration settings and policy violation alerts.

CM-7 (Least Functionality):

• Vendor Implementation: Disable unnecessary features and services by default
• Product Requirements: Implement minimal installation footprint with optional feature enablement
• Implementation Notes: Include feature flags, service disablement, and functionality auditing. Already planned: minimal attack surface design with three-component architecture and privilege separation. Additional work needed: feature flags and service disablement controls.

CM-8 (System Component Inventory):

• Vendor Implementation: Real-time inventory of all system components and dependencies
• Product Requirements: Implement component discovery, dependency tracking, and inventory reporting
• Implementation Notes: Include SBOM generation, vulnerability scanning, and component lifecycle management. Already planned: three-component architecture with clear component separation and dependency management. Additional work needed: real-time inventory tracking and SBOM generation.

Contingency Planning (CP) Family

CP-2 (Contingency Plan):

• Vendor Implementation: Documented contingency plans for DaemonEye operations
• Product Requirements: Provide disaster recovery procedures, failover documentation, and recovery time objectives
• Implementation Notes: Include automated failover, data replication, and recovery procedures. Already planned: graceful degradation under resource constraints and fail-safe design. Additional work needed: formal contingency plans and disaster recovery procedures.

CP-6 (Alternate Storage Sites):

• Vendor Implementation: Backup data storage capabilities
• Product Requirements: Implement data backup, replication, and archival capabilities
• Implementation Notes: Include automated backups, data integrity verification, and recovery testing. Already planned: redb database with ACID transactions and data integrity verification. Additional work needed: automated backup scheduling and alternate storage site capabilities.

CP-7 (Alternate Processing Sites):

• Vendor Implementation: Failover capabilities for critical operations
• Product Requirements: Implement high availability, load balancing, and failover mechanisms
• Implementation Notes: Include health monitoring, automatic failover, and service restoration. Already planned: resource management with graceful degradation and circuit breaker patterns. Additional work needed: high availability and load balancing mechanisms.

CP-9 (System Backup):

• Vendor Implementation: Automated backup and recovery procedures
• Product Requirements: Implement automated backup scheduling, data verification, and recovery procedures
• Implementation Notes: Include incremental backups, compression, encryption, and recovery testing. Already planned: redb database with data integrity verification and ACID transactions. Additional work needed: automated backup scheduling and recovery procedures.

CP-10 (System Recovery and Reconstitution):

• Vendor Implementation: Documented recovery procedures
• Product Requirements: Provide recovery documentation, testing procedures, and validation methods
• Implementation Notes: Include recovery automation, validation scripts, and testing frameworks. Already planned: graceful degradation and fail-safe design with resource management. Additional work needed: formal recovery procedures and validation methods.

Identification and Authentication (IA) Family

IA-3 (Device Identification and Authentication):

• Vendor Implementation: Device authentication for agent connections
• Product Requirements: Implement device certificates, mutual TLS, and device identity verification
• Implementation Notes: Include certificate management, device enrollment, and authentication protocols. Device authentication for agent connections and device identity verification remain open items for this repo.

IA-4 (Identifier Management):

• Vendor Implementation: Unique identifier management for all system components
• Product Requirements: Implement unique component identification, identifier generation, and management
• Implementation Notes: Include UUID generation, identifier persistence, and identifier validation. Already planned: three-component architecture with clear component identification and separation. Additional work needed: unique identifier management and identifier generation.

IA-5 (Authenticator Management):

• Vendor Implementation: Secure management of authentication credentials
• Product Requirements: Implement credential storage, rotation, and management
• Implementation Notes: Include secure storage, credential rotation, and access controls. Already planned: secure credential management through environment variables and OS keychain integration. Additional work needed: credential rotation and formal authenticator management.

IA-7 (Cryptographic Module Authentication):

• Vendor Implementation: Authentication for cryptographic modules
• Product Requirements: Implement cryptographic module authentication and validation
• Implementation Notes: Include module verification, authentication protocols, and security validation. Already planned: BLAKE3 cryptographic hashing and Ed25519 signatures for audit integrity. Additional work needed: cryptographic module authentication and validation.

Incident Response (IR) Family

IR-4 (Incident Handling):

• Vendor Implementation: Automated incident detection and response capabilities
• Product Requirements: Implement incident detection, automated response, and escalation procedures
• Implementation Notes: Include threat detection, automated containment, and response workflows. Already planned: SQL-based detection engine with automated alert generation and multi-channel alert delivery. Additional work needed: automated incident response and escalation procedures.

IR-5 (Incident Monitoring):

• Vendor Implementation: Continuous monitoring for security incidents
• Product Requirements: Implement real-time monitoring, threat detection, and incident tracking
• Implementation Notes: Include monitoring dashboards, alert correlation, and incident tracking. Already planned: continuous process monitoring with real-time threat detection and structured alert generation. Additional work needed: monitoring dashboards and incident tracking.

IR-6 (Incident Reporting):

• Vendor Implementation: Automated reporting to US-CERT and other authorities
• Product Requirements: Implement incident reporting, notification systems, and compliance reporting
• Implementation Notes: Include automated reporting, notification templates, and compliance integration. Already planned: structured alert generation with multiple delivery channels and compliance reporting capabilities. Additional work needed: automated reporting to authorities and notification templates.

Maintenance (MA) Family

MA-3 (Maintenance Tools):

• Vendor Implementation: Secure maintenance tools and procedures
• Product Requirements: Implement secure maintenance interfaces, tools, and procedures
• Implementation Notes: Include maintenance authentication, tool validation, and procedure documentation. Already planned: comprehensive development tools and testing frameworks with security validation. Additional work needed: secure maintenance interfaces and formal maintenance procedures.

MA-4 (Nonlocal Maintenance):

• Vendor Implementation: Secure remote maintenance capabilities
• Product Requirements: Implement secure remote access, maintenance protocols, and access controls
• Implementation Notes: Include encrypted channels, authentication, and access logging. Already planned: authenticated IPC channels and secure communication protocols. Additional work needed: secure remote maintenance capabilities and access controls.

Risk Assessment (RA) Family

RA-5 (Vulnerability Scanning):

• Vendor Implementation: Automated vulnerability scanning
• Product Requirements: Implement vulnerability scanning, assessment, and reporting
• Implementation Notes: Include automated scanning, vulnerability databases, and remediation guidance. Already planned: automated dependency scanning and vulnerability management with security tools integration. Additional work needed: vulnerability scanning capabilities and remediation guidance.

System and Services Acquisition (SA) Family

SA-3 (System Development Life Cycle):

• Vendor Implementation: Security integration in SDLC
• Product Requirements: Implement secure development practices, security testing, and validation
• Implementation Notes: Include security requirements, testing frameworks, and validation procedures. Already planned: comprehensive testing strategy with unit, integration, and fuzz testing, plus security-focused development practices. Additional work needed: formal SDLC security integration and validation procedures.

SA-4 (Acquisition Process):

• Vendor Implementation: Secure acquisition process
• Product Requirements: Implement secure distribution, verification, and installation procedures
• Implementation Notes: Include code signing, package verification, and secure distribution. Code signing and integrity verification remain open items for this repo. Additional work needed: secure acquisition process and package verification.

SA-5 (Information System Documentation):

• Vendor Implementation: Comprehensive system documentation
• Product Requirements: Provide complete documentation, security guides, and operational procedures
• Implementation Notes: Include technical documentation, security guides, and compliance documentation. Already planned: comprehensive documentation including AGENTS.md, .kiro/steering/development.md, and technical specifications. Additional work needed: formal system documentation and compliance documentation.

SA-8 (Security Engineering Principles):

• Vendor Implementation: Security engineering principles
• Product Requirements: Implement security-by-design, secure coding practices, and security validation
• Implementation Notes: Include secure architecture, coding standards, and security validation. Already planned: security-first architecture with privilege separation, minimal attack surface, and defense-in-depth design. Additional work needed: formal security engineering principles and validation procedures.

SA-11 (Developer Security Testing and Evaluation):

• Vendor Implementation: Security testing by developers
• Product Requirements: Implement security testing, vulnerability assessment, and validation
• Implementation Notes: Include automated testing, security scanning, and validation frameworks. Already planned: comprehensive testing strategy with unit, integration, fuzz testing, and security-focused development practices. Additional work needed: formal security testing and evaluation procedures.

SA-12 (Supply Chain Protection):

• Vendor Implementation: Supply chain security controls
• Product Requirements: Implement supply chain security, dependency management, and verification
• Implementation Notes: Include SBOM generation, dependency scanning, and supply chain validation. Already planned: automated dependency scanning and vulnerability management with security tools integration. Additional work needed: SBOM generation and supply chain validation.

SA-15 (Development Process, Standards, and Tools):

• Vendor Implementation: Secure development processes
• Product Requirements: Implement secure development practices, standards, and tools
• Implementation Notes: Include development standards, security tools, and process validation. Already planned: comprehensive development workflow with security-focused practices and quality gates. Additional work needed: formal development process standards and tool validation.

SA-16 (Developer-Provided Training):

• Vendor Implementation: Security training for developers
• Product Requirements: Provide security training, documentation, and best practices
• Implementation Notes: Include training materials, security guidelines, and best practices. Already planned: comprehensive documentation including AGENTS.md, .kiro/steering/development.md, and technical specifications. Additional work needed: formal security training materials and developer guidelines.

SA-17 (Developer Security Architecture and Design):

• Vendor Implementation: Security architecture and design
• Product Requirements: Implement secure architecture, design patterns, and security controls
• Implementation Notes: Include security architecture, design patterns, and control implementation. Already planned: three-component security architecture with privilege separation and minimal attack surface design. Additional work needed: formal security architecture documentation and design patterns.

SA-18 (Tamper Resistance and Detection):

• Vendor Implementation: Tamper resistance and detection
• Product Requirements: Implement tamper detection, integrity verification, and protection mechanisms
• Implementation Notes: Include integrity checking, tamper detection, and protection mechanisms. Code signing verification and integrity checking remain open items for this repo. Additional work needed: enhanced tamper detection and protection mechanisms.

SA-19 (Component Authenticity):

• Vendor Implementation: Component authenticity verification
• Product Requirements: Implement component verification, authenticity checking, and validation
• Implementation Notes: Include signature verification, authenticity validation, and integrity checking. Code signing and integrity verification remain open items for this repo. Additional work needed: component authenticity verification and validation.

SA-20 (Customized Development of Critical Components):

• Vendor Implementation: Custom development of critical components
• Product Requirements: Implement custom security components, specialized functionality, and enhanced security
• Implementation Notes: Include custom development, specialized components, and enhanced security. Already planned: three-component architecture with specialized security functions and custom cryptographic implementations. Additional work needed: formal custom development procedures and specialized component documentation.

SA-21 (Developer Screening):

• Vendor Implementation: Background screening for developers
• Product Requirements: Implement developer vetting, access controls, and security clearance
• Implementation Notes: Include background checks, access controls, and security clearance. Already planned: comprehensive development workflow with security-focused practices and quality gates. Additional work needed: formal developer screening procedures and access controls.

SA-22 (Unsupported System Components):

• Vendor Implementation: Management of unsupported components
• Product Requirements: Implement component lifecycle management, deprecation handling, and migration support
• Implementation Notes: Include lifecycle management, deprecation procedures, and migration support. Already planned: three-component architecture with clear component separation and dependency management. Additional work needed: formal component lifecycle management and deprecation procedures.

Enhanced System and Communications Protection (SC) Family

SC-1 (System and Communications Protection Policy and Procedures):

• Vendor Implementation: Document comprehensive SC policies and procedures for DaemonEye deployment
• Product Requirements: Provide security configuration guides, network isolation procedures, and communication protocols
• Implementation Notes: Include deployment hardening guides, security configuration templates, and operational procedures for airgapped environments. Already planned: comprehensive security configuration guides, operational procedures, and development workflow documentation. Additional work needed: formal SC policy documentation and deployment hardening guides.

SC-2 (Application Partitioning):

• Vendor Implementation: Implement strict application partitioning in DaemonEye’s three-component architecture
• Product Requirements: Ensure procmond, daemoneye-agent, and daemoneye-cli operate in isolated process spaces with defined interfaces
• Implementation Notes: Use process isolation, separate memory spaces, and controlled IPC communication channels between components. Already planned: three-component architecture with procmond (privileged collector), daemoneye-agent (user-space orchestrator), and daemoneye-cli (command interface) operating in isolated process spaces. Additional work needed: enhanced partitioning controls and formal partitioning documentation.

SC-3 (Security Function Isolation):

• Vendor Implementation: Isolate security functions within dedicated components (procmond for collection, daemoneye-agent for detection)
• Product Requirements: Implement privilege separation with minimal privilege requirements per component
• Implementation Notes: Use platform-specific capabilities (Linux capabilities, Windows privileges) with immediate privilege dropping after initialization. Already planned: privilege separation with immediate privilege dropping after initialization, platform-specific capability management for Linux, Windows, and macOS. Additional work needed: enhanced isolation controls and formal isolation documentation.

SC-4 (Information in Shared Resources):

• Vendor Implementation: Protect sensitive information in shared IPC channels and database storage
• Product Requirements: Implement data protection in shared resources, with access controls for shared resources
• Implementation Notes: Use CRC32 integrity verification for IPC messages (local memory only), database encryption for stored data, and access control lists for shared files. Already planned: IPC security with protobuf message serialization and CRC32 integrity verification for local inter-process communication. Additional work needed: database encryption at rest and enhanced access controls for shared resources.

SC-5 (Denial of Service Protection):

• Vendor Implementation: Implement DoS protection mechanisms for DaemonEye components
• Product Requirements: Provide resource quotas, memory limits, and protection against resource exhaustion attacks
• Implementation Notes: Include memory limits, CPU usage bounds, database connection limits, and graceful degradation under resource constraints. Note: DaemonEye has no inbound network communications, so network-based DoS attacks are not applicable. Already planned: resource management with bounded channels, memory limits, timeout support, and circuit breaker patterns for external dependencies. Additional work needed: enhanced resource protection and formal DoS protection documentation.

SC-6 (Resource Availability):

• Vendor Implementation: Ensure resource availability controls for DaemonEye operations
• Product Requirements: Implement resource monitoring, automatic recovery, and failover mechanisms
• Implementation Notes: Include health monitoring, automatic restart capabilities, and resource usage tracking with alerts. Already planned: resource management with graceful degradation, bounded channels, and cooperative yielding under resource constraints. Additional work needed: enhanced failover mechanisms and formal resource availability documentation.

SC-9 (Transmission Confidentiality):

• Vendor Implementation: Ensure transmission confidentiality for all DaemonEye communications
• Product Requirements: Implement encryption for IPC channels, alert delivery, and data transmission
• Implementation Notes: Use TLS for webhook alerts, encrypted IPC channels, and secure data export formats. Already planned: TLS for webhook alert delivery and secure data export formats for SIEM integration. Additional work needed: enhanced encryption for IPC channels and formal transmission confidentiality documentation.

SC-10 (Network Disconnect):

• Vendor Implementation: Support network disconnect capabilities for airgapped deployments
• Product Requirements: Ensure full functionality without network connectivity, with graceful degradation of network-dependent features
• Implementation Notes: Implement offline operation modes, local alert storage, and bundle-based configuration distribution. Already planned: offline-first operation with full functionality without internet access, bundle-based configuration distribution for airgapped environments, and graceful degradation of network-dependent features. Additional work needed: enhanced airgapped deployment documentation and formal network disconnect procedures.

SC-11 (Trusted Path):

• Vendor Implementation: Provide trusted path for critical DaemonEye operations
• Product Requirements: Implement secure communication channels for administrative operations and configuration changes
• Implementation Notes: Use authenticated IPC channels, secure configuration interfaces, and protected administrative access. Already planned: authenticated IPC channels with connection authentication and optional encryption for secure inter-process communication. Additional work needed: enhanced trusted path mechanisms and formal trusted path documentation.

SC-16 (Transmission of Security Attributes):

• Vendor Implementation: Transmit security attributes with all DaemonEye data and communications. Data classification support is an open item for this repo. Additional Required: Enhanced security attribute transmission and formal security attribute documentation.
• Product Requirements: Include data classification, sensitivity labels, and security markings in all transmissions
• Implementation Notes: Embed security attributes in protobuf messages, database records, and alert payloads

SC-17 (Public Key Infrastructure Certificates):

• Vendor Implementation: Implement PKI certificate management for DaemonEye components. PKI and certificate management are out of scope for this repo. Additional Required: Enhanced PKI certificate management and formal PKI documentation.
• Product Requirements: Support certificate-based authentication, mutual TLS, and certificate validation
• Implementation Notes: Include certificate generation, validation, rotation, and revocation for agent authentication and alert delivery

SC-18 (Mobile Code):

• Vendor Implementation: Control mobile code execution in DaemonEye environment. Additional Required: Enhanced mobile code controls and formal mobile code documentation.
• Product Requirements: Implement controls for mobile code execution and validation
• Implementation Notes: Include code signing verification, execution sandboxing, and mobile code validation

SC-19 (Voice Over Internet Protocol):

• Vendor Implementation: Secure VoIP communications for DaemonEye (if applicable). Not Currently Planned: VoIP communications are not part of the current DaemonEye design. Additional Required: VoIP security controls if voice communications are added to the product.

• Product Requirements: Implement encryption and security controls for VoIP communications

• Implementation Notes: Include VoIP encryption, authentication, and security protocols for voice communications SC-20 (Secure Name/Address Resolution Service):

• Vendor Implementation: Implement secure DNS resolution for DaemonEye. Not Currently Planned: DNS resolution is not part of the current DaemonEye design. Additional Required: Secure DNS resolution capabilities if DNS functionality is added to the product.

• Product Requirements: Provide secure name resolution and address resolution services

• Implementation Notes: Include DNS over TLS, DNS over HTTPS, and secure DNS configuration

SC-21 (Secure Name/Address Resolution Service (Recursive or Caching Resolver)):

• Vendor Implementation: Implement secure recursive DNS resolution for DaemonEye. Not Currently Planned: DNS resolution is not part of the current DaemonEye design. Additional Required: Secure recursive DNS resolution capabilities if DNS functionality is added to the product.
• Product Requirements: Provide secure recursive DNS resolution with caching capabilities
• Implementation Notes: Include secure recursive DNS, DNS caching security, and resolution validation

SC-22 (Architecture and Provisioning for Name/Address Resolution Service):

• Vendor Implementation: Design secure DNS architecture for DaemonEye. Not Currently Planned: DNS architecture is not part of the current DaemonEye design. Additional Required: Secure DNS architecture if DNS functionality is added to the product.
• Product Requirements: Implement secure DNS architecture and provisioning
• Implementation Notes: Include secure DNS infrastructure, provisioning automation, and architecture security

SC-23 (Session Authenticity):

• Vendor Implementation: Ensure session authenticity for DaemonEye administrative sessions. Already Planned: Authentication and integrity verification are specified in tech.md. Additional Required: Enhanced session management and formal session authenticity documentation.
• Product Requirements: Implement session management, authentication, and integrity verification
• Implementation Notes: Use secure session tokens, session timeout controls, and cryptographic session validation

SC-24 (Fail in Known State):

• Vendor Implementation: Ensure DaemonEye fails in a known, secure state. Additional Required: Enhanced fail-safe mechanisms and formal fail-safe documentation.
• Product Requirements: Implement fail-safe mechanisms that maintain security boundaries during failures
• Implementation Notes: Include graceful shutdown procedures, secure state preservation, and recovery from known states

SC-25 (Thin Nodes):

• Vendor Implementation: Support thin client security for DaemonEye. Not Currently Planned: Thin client deployments are not part of the current DaemonEye design. Additional Required: Thin client security controls if thin client functionality is added to the product.
• Product Requirements: Implement security controls for thin client deployments
• Implementation Notes: Include thin client authentication, secure communication, and minimal client footprint

SC-26 (Honeypots):

• Vendor Implementation: Implement honeypot capabilities for DaemonEye. Not Currently Planned: Honeypot capabilities are not part of the current DaemonEye design. Additional Required: Honeypot capabilities if threat intelligence collection is expanded.
• Product Requirements: Provide decoy systems and monitoring capabilities for threat detection
• Implementation Notes: Include honeypot deployment, monitoring capabilities, and threat intelligence collection

SC-27 (Platform-Independent Applications):

• Vendor Implementation: Ensure DaemonEye operates consistently across different platforms. Already Planned: Cross-platform support and OS support matrix are specified in tech.md. Additional Required: Enhanced platform independence testing and formal platform independence documentation.
• Product Requirements: Provide platform-independent security controls and consistent behavior
• Implementation Notes: Use cross-platform libraries, consistent security policies, and platform-specific optimizations where needed

SC-29 (Heterogeneity):

• Vendor Implementation: Support heterogeneous system environments for DaemonEye deployment. Already Planned: Multi-platform support and OS support matrix are specified in tech.md. Additional Required: Enhanced heterogeneity testing and formal heterogeneity documentation.
• Product Requirements: Ensure compatibility across different operating systems, architectures, and configurations
• Implementation Notes: Include multi-platform support, architecture-specific optimizations, and configuration flexibility

SC-30 (Concealment and Misdirection):

• Vendor Implementation: Implement concealment and misdirection capabilities for DaemonEye. Not Currently Planned: Concealment and misdirection capabilities are not part of the current DaemonEye design. Additional Required: Concealment and misdirection capabilities if advanced threat detection is expanded.
• Product Requirements: Provide decoy systems and misdirection techniques for threat detection
• Implementation Notes: Include honeypot deployment, decoy data generation, and misdirection techniques

SC-31 (Covert Channel Analysis):

• Vendor Implementation: Analyze and mitigate covert channels in DaemonEye design. Already Planned: Resource usage monitoring and channel capacity limitations are specified in tech.md. Additional Required: Enhanced covert channel analysis and formal covert channel documentation.
• Product Requirements: Implement controls to prevent information leakage through covert channels
• Implementation Notes: Include timing analysis, resource usage monitoring, and channel capacity limitations

SC-32 (Information System Partitioning):

• Vendor Implementation: Implement system partitioning in DaemonEye architecture. Additional Required: Enhanced system partitioning and formal partitioning documentation.
• Product Requirements: Ensure logical and physical separation of different security domains
• Implementation Notes: Use process isolation, separate databases, and controlled data flow between partitions

SC-33 (Transmission Preparation Integrity):

• Vendor Implementation: Ensure integrity of data preparation for transmission. Already Planned: CRC32 integrity verification and data validation are specified in tech.md. Additional Required: Enhanced transmission integrity and formal transmission integrity documentation.
• Product Requirements: Implement data validation, checksums, and integrity verification before transmission
• Implementation Notes: Use CRC32 checksums, data validation, and integrity verification for all IPC and network communications

SC-34 (Modifiable Components):

• Vendor Implementation: Control modification of DaemonEye components. Additional Required: Enhanced tamper detection and formal modification control documentation.
• Product Requirements: Implement tamper detection, code signing verification, and modification controls
• Implementation Notes: Include integrity checking, signature verification, and protection against unauthorized modifications

SC-35 (Honeytokens):

• Vendor Implementation: Implement honeytoken capabilities for DaemonEye. Not Currently Planned: Honeytoken capabilities are not part of the current DaemonEye design. Additional Required: Honeytoken capabilities if advanced threat detection is expanded.
• Product Requirements: Provide decoy data and monitoring capabilities for threat detection
• Implementation Notes: Include fake process data, decoy alerts, and monitoring of access to honeytoken data

SC-36 (Distributed Processing and Storage):

• Vendor Implementation: Support distributed processing and storage for DaemonEye. Additional Required: Enhanced distributed processing and formal distributed architecture documentation.
• Product Requirements: Implement distributed architecture with secure communication and data consistency
• Implementation Notes: Distributed processing and multi-node aggregation are commercial-tier concerns, handled outside this repo.

SC-37 (Out-of-Band Channels):

• Vendor Implementation: Support out-of-band communication channels for DaemonEye. Additional Required: Enhanced out-of-band channels and formal out-of-band documentation.
• Product Requirements: Implement alternative communication methods for critical operations
• Implementation Notes: Include secure out-of-band alert delivery, administrative access, and emergency communication channels

SC-38 (Operations Security):

• Vendor Implementation: Implement operations security controls for DaemonEye. Already Planned: Operational security procedures are documented in AGENTS.md and .kiro/steering/development.md. Additional Required: Enhanced operations security and formal operations security documentation.

• Product Requirements: Protect operational information and prevent information leakage

• Implementation Notes: Include operational security procedures, information protection, and security awareness training SC-40 (Wireless Link Protection):

• Vendor Implementation: Protect wireless communications for DaemonEye (if applicable). Not Currently Planned: Wireless communications are not part of the current DaemonEye design. Additional Required: Wireless security controls if wireless functionality is added to the product.

• Product Requirements: Implement encryption and security controls for wireless communications

• Implementation Notes: Include wireless security protocols, encryption, and access controls for wireless deployments

SC-41 (Port and I/O Device Access):

• Vendor Implementation: Control access to ports and I/O devices for DaemonEye. Not Currently Planned: Port and I/O device access controls are not part of the current DaemonEye design. Additional Required: Port and I/O device access controls if device access functionality is added to the product.
• Product Requirements: Implement access controls and monitoring for system ports and devices
• Implementation Notes: Include device access controls, port monitoring, and I/O device security policies

SC-42 (Sensor Capability and Data):

• Vendor Implementation: Implement sensor capabilities and data protection for DaemonEye. Additional Required: Enhanced sensor capabilities and formal sensor documentation.
• Product Requirements: Provide sensor data collection, processing, and protection capabilities
• Implementation Notes: Include process monitoring sensors, data collection security, and sensor data integrity verification

SC-43 (Usage Restrictions):

• Vendor Implementation: Implement usage restrictions for DaemonEye components. Already Planned: Resource usage limits and capability restrictions are specified in tech.md. Additional Required: Enhanced usage restrictions and formal usage restriction documentation.
• Product Requirements: Control and monitor usage of system resources and capabilities
• Implementation Notes: Include resource usage limits, capability restrictions, and usage monitoring and reporting

SC-44 (Detachable Media):

• Vendor Implementation: Control access to detachable media for DaemonEye. Not Currently Planned: Detachable media controls are not part of the current DaemonEye design. Additional Required: Detachable media controls if media access functionality is added to the product.
• Product Requirements: Implement controls for removable media access and data protection
• Implementation Notes: Include media access controls, data encryption for removable media, and media sanitization procedures

SC-45 (System Time Synchronization):

• Vendor Implementation: Ensure time synchronization for DaemonEye components. Additional Required: Enhanced time synchronization and formal time synchronization documentation.
• Product Requirements: Implement accurate time synchronization and time-based security controls
• Implementation Notes: Include NTP synchronization, time validation, and timestamp integrity verification

SC-46 (Cross-Service Attack Prevention):

• Vendor Implementation: Prevent cross-service attacks in DaemonEye. Additional Required: Enhanced cross-service attack prevention and formal attack prevention documentation.
• Product Requirements: Implement isolation and protection between different services and components
• Implementation Notes: Include service isolation, access controls, and monitoring for cross-service attack attempts

SC-47 (Alternate Communications Paths):

• Vendor Implementation: Provide alternate communication paths for DaemonEye. Additional Required: Enhanced alternate communication paths and formal communication path documentation.
• Product Requirements: Implement redundant communication channels and failover mechanisms
• Implementation Notes: Include multiple alert delivery channels, backup communication methods, and automatic failover

SC-48 (Application Partitioning):

• Vendor Implementation: Implement application partitioning for DaemonEye security. Additional Required: Enhanced application partitioning and formal partitioning documentation.

• Product Requirements: Ensure logical separation of application components and data

• Implementation Notes: Include component isolation, data separation, and controlled interfaces between partitions SC-49 (Replay-Resistant Authentication):

• Vendor Implementation: Implement replay-resistant authentication for DaemonEye. Already Planned: Authentication mechanisms are specified in tech.md. Additional Required: Enhanced replay-resistant authentication and formal authentication documentation.

• Product Requirements: Provide authentication mechanisms that resist replay attacks

• Implementation Notes: Include nonce-based authentication, timestamp validation, and replay attack prevention

SC-50 (Software-Enforced Separation):

• Vendor Implementation: Implement software-enforced separation in DaemonEye. Additional Required: Enhanced software-enforced separation and formal separation documentation.
• Product Requirements: Use software controls to enforce security boundaries and separation
• Implementation Notes: Include process isolation, memory protection, and access control enforcement

SC-51 (Hardware-Based Security):

• Vendor Implementation: Leverage hardware-based security features for DaemonEye. Additional Required: Enhanced hardware-based security and formal hardware security documentation.
• Product Requirements: Utilize hardware security modules and trusted platform modules where available
• Implementation Notes: Include HSM integration, TPM support, and hardware-based key storage

SC-52 (Portable Storage Devices):

• Vendor Implementation: Control portable storage device access for DaemonEye. Not Currently Planned: Portable storage device controls are not part of the current DaemonEye design. Additional Required: Portable storage device controls if device access functionality is added to the product.
• Product Requirements: Implement controls for portable storage devices and data protection
• Implementation Notes: Include device access controls, data encryption, and portable storage security policies

SC-53 (Enforceable Flow Control):

• Vendor Implementation: Implement enforceable flow control for DaemonEye. Already Planned: Data flow monitoring and access controls are specified in tech.md. Additional Required: Enhanced flow control and formal flow control documentation.
• Product Requirements: Control and monitor data flow between system components
• Implementation Notes: Include data flow monitoring, access controls, and flow restriction mechanisms

SC-54 (Shared Memory):

• Vendor Implementation: Protect shared memory in DaemonEye. Already Planned: Memory access controls are specified in tech.md. Additional Required: Enhanced shared memory protection and formal shared memory documentation.
• Product Requirements: Implement secure shared memory access and protection
• Implementation Notes: Include memory access controls, shared memory encryption, and access monitoring

SC-55 (Enforceable Access Control):

• Vendor Implementation: Implement enforceable access control for DaemonEye. Additional Required: Enhanced access control and formal access control documentation.
• Product Requirements: Provide mandatory access controls and enforcement mechanisms
• Implementation Notes: Include role-based access control, mandatory access controls, and access enforcement

SC-56 (Enforceable Execution Domains):

• Vendor Implementation: Implement enforceable execution domains for DaemonEye. Additional Required: Enhanced execution domains and formal execution domain documentation.
• Product Requirements: Control execution environments and domain boundaries
• Implementation Notes: Include execution isolation, domain separation, and execution environment controls

SC-57 (Data Location):

• Vendor Implementation: Control data location for DaemonEye. Additional Required: Enhanced data location controls and formal data location documentation.
• Product Requirements: Implement data residency controls and location restrictions
• Implementation Notes: Include data location tracking, residency controls, and geographic restrictions

SC-58 (Secure Operations):

• Vendor Implementation: Ensure secure operations for DaemonEye. Already Planned: Secure configuration and operational security procedures are documented in AGENTS.md and .kiro/steering/development.md. Additional Required: Enhanced secure operations and formal secure operations documentation.
• Product Requirements: Implement secure operational procedures and controls
• Implementation Notes: Include secure configuration, operational security procedures, and security monitoring

SC-59 (Information Flow Enforcement):

• Vendor Implementation: Implement information flow enforcement for DaemonEye. Already Planned: Information flow monitoring is specified in tech.md. Additional Required: Enhanced information flow enforcement and formal information flow documentation.
• Product Requirements: Control and monitor information flow between system components
• Implementation Notes: Include data flow controls, information flow monitoring, and flow restriction enforcement

Implementation Priority

High Priority (Core Security Controls):

• Configuration Management (CM-2, CM-3, CM-4, CM-5, CM-6, CM-7, CM-8)
• Incident Response (IR-4, IR-5, IR-6)
• Risk Assessment (RA-5)
• System and Services Acquisition (SA-3, SA-4, SA-5, SA-8, SA-11, SA-12, SA-15, SA-16, SA-17, SA-18, SA-19, SA-20, SA-21, SA-22)

Medium Priority (Operational Controls):

• Contingency Planning (CP-2, CP-6, CP-7, CP-9, CP-10)
• Identification and Authentication (IA-3, IA-4, IA-5, IA-7)
• Maintenance (MA-3, MA-4)
• Enhanced System and Communications Protection (SC-2, SC-3, SC-4, SC-5, SC-6, SC-9, SC-10, SC-11, SC-16, SC-17, SC-23, SC-24, SC-27, SC-29, SC-31, SC-32, SC-33, SC-34, SC-35, SC-36, SC-37, SC-38, SC-40, SC-41, SC-42, SC-43, SC-44, SC-45, SC-46, SC-47, SC-48, SC-49, SC-50, SC-51, SC-52, SC-53, SC-54, SC-55, SC-56, SC-57, SC-58, SC-59)

Excluded Controls (End-Consumer Responsibilities):

• Personnel Security (PS-1 through PS-6): Personnel management is the responsibility of the deploying organization
• Physical and Environmental Protection (PE-1 through PE-6): Physical security is the responsibility of the deploying organization
• Contingency Training (CP-3, CP-4): Training programs are the responsibility of the deploying organization
• Incident Response Training (IR-2, IR-3): Training programs are the responsibility of the deploying organization
• Maintenance Personnel (MA-5): Personnel management is the responsibility of the deploying organization
• Media Protection (MP-1 through MP-6): Media handling is the responsibility of the deploying organization
• Risk Assessment (RA-1, RA-2, RA-3): Risk assessment is the responsibility of the deploying organization
• System and Services Acquisition (SA-1, SA-2): Acquisition processes are the responsibility of the deploying organization

Deployment Security Considerations

Installation Security

Package Integrity:

• Code signing for all distributions
• Cryptographic verification of packages
• Secure distribution channels
• Installation audit logging

Privilege Requirements:

• Minimal installation privileges
• Service account creation
• File system permissions
• Network configuration

Configuration Hardening:

• Secure default configurations
• Security policy templates
• Environment-specific hardening
• Compliance checklists

Runtime Security

Process Isolation:

• Container security (if applicable)
• Systemd security features
• SELinux/AppArmor integration
• Resource limits and quotas

Network Security:

• Firewall configuration
• Network segmentation
• Traffic monitoring
• Intrusion detection

Monitoring Integration:

• SIEM integration
• Log aggregation
• Metrics collection
• Alert correlation

Maintenance Security

Update Procedures:

• Secure update channels
• Rollback capabilities
• Testing procedures
• Change management

Access Management:

• Principle of least privilege
• Regular access reviews
• Multi-factor authentication
• Audit logging

Incident Response:

• Response procedures
• Evidence collection
• Communication protocols
• Recovery procedures

Footnotes

Conclusion

DaemonEye’s security design provides a comprehensive framework for secure process monitoring and threat detection. The three-component architecture with strict privilege separation, cryptographic integrity verification, and comprehensive audit logging ensures that the system meets enterprise security requirements while maintaining high performance and operational efficiency.

The system’s defense-in-depth approach, combined with its air-gap compatibility and compliance features, makes it suitable for deployment in high-security environments where traditional monitoring solutions may not meet security requirements.

For additional technical details, refer to the API Reference and Deployment Guide documentation.

1. Requirement 6.2: Request platform-specific privileges (CAP_SYS_PTRACE on Linux, SeDebugPrivilege on Windows) ↩

2. Requirement 6.3: Immediately drop all elevated privileges after initialization ↩

3. Requirement 2.1: SHA-256 computation for executable integrity verification ↩ ↩2

4. Requirement 6.5: Log all privilege changes for audit trail ↩

5. Requirement 3.1: Parse SQL queries using AST validation to prevent injection attacks ↩ ↩2

6. Requirement 3.3: Use prepared statements with read-only database connections ↩ ↩2

7. Requirement 3.4: Complete within 30 seconds or timeout with appropriate logging ↩ ↩2

8. Requirement 5.2: Implement circuit breaker pattern for failing channels ↩

9. Requirement 3.5: Reject forbidden constructs and log attempts for audit purposes ↩ ↩2

10. Requirement 3.2: Only allow SELECT statements with approved functions (COUNT, SUM, AVG, MIN, MAX, LENGTH, SUBSTR, datetime functions) ↩

11. Requirement 8.1: Execute user-provided SQL queries with parameterization and prepared statements ↩

12. Requirement 8.2: Support JSON, human-readable table, and CSV output formats ↩

13. Requirement 8.3: Provide capabilities to list, validate, test, and import/export detection rules ↩

14. Requirement 8.4: Display component status with color-coded indicators ↩

15. Requirement 8.5: Support streaming and pagination for result sets ↩

16. Requirement 7.3: Use BLAKE3 for fast, cryptographically secure hash computation ↩ ↩2

17. Requirement 7.4: Provide chain verification function to detect tampering ↩ ↩2

18. Requirement 7.1: Record security events in append-only audit ledger with monotonic sequence numbers ↩

19. Requirement 7.5: Millisecond-precision timestamps for audit events ↩ ↩2

20. Requirement 1.2: CPU usage < 5% sustained during continuous monitoring ↩

21. Requirement 1.1: Process enumeration < 5 seconds for systems with up to 10,000 processes ↩

22. Requirement 3.4: Detection rule timeout 30 seconds maximum execution time ↩

23. Requirement 5.3: Alert delivery retry up to 3 attempts with maximum 60-second delay ↩ ↩2

24. Enterprise Requirement 1.4: Sub-millisecond latency from event occurrence to detection ↩

25. Enterprise Requirement 2.6: Fleet query response < 60 seconds for up to 10,000 endpoints ↩

26. Enterprise Requirement 7.1: CPU overhead < 2% per monitored endpoint for 10,000+ processes ↩

27. Enterprise Requirement 7.2: 100,000+ events per minute with sub-second query response ↩

28. Requirement 10.1: Use structured JSON format with consistent field naming and configurable log levels ↩ ↩2 ↩3

29. Requirement 10.4: Embed performance metrics in log entries with correlation IDs ↩

30. Requirement 10.2: Provide Prometheus-compatible metrics for collection rate, detection latency, and alert delivery ↩

31. Requirement 10.3: Expose HTTP health endpoints with component-level status checks ↩

32. Requirement 4.1: Generate alert with timestamp, severity, rule_id, title, and description ↩

33. Requirement 4.2: Include affected process details (PID, name, executable path) ↩

34. Requirement 4.3: Support four severity levels (low, medium, high, critical) ↩

35. Requirement 4.4: Implement deduplication using configurable keys ↩

36. Requirement 4.5: Store alerts in database with delivery tracking information ↩

37. Requirement 5.1: Support multiple sinks including stdout, syslog, webhook, email, and file output ↩

38. Requirement 5.2: Implement circuit breaker pattern with configurable failure thresholds ↩

39. Requirement 5.4: Store failed alerts in dead letter queue for later processing ↩

40. Requirement 5.5: Process alerts to multiple sinks in parallel without blocking other deliveries ↩

41. Requirement 9.1: All core functionality continues operating normally when network connectivity is unavailable ↩

42. Requirement 9.2: Process enumeration, detection rules, and database operations function without degradation ↩

43. Requirement 9.3: Alert delivery degrades gracefully with local sinks continuing to work ↩

44. Requirement 9.4: Support bundle-based configuration and rule distribution for airgapped systems ↩

45. Requirement 9.5: Validate and apply bundles atomically with conflict resolution ↩

Testing Documentation

This document provides comprehensive testing strategies and guidelines for DaemonEye, covering unit testing, integration testing, performance testing, and security testing.

Table of Contents

• Testing Philosophy
• Testing Strategy
  • Three-Tier Testing Architecture
  • Testing Pyramid
• Unit Testing
  • Core Testing Framework
  • Mocking and Test Doubles
  • Property-Based Testing
• Integration Testing
  • Database Integration Tests
  • IPC Integration Tests
  • Alert Delivery Integration Tests
• End-to-End Testing
  • CLI Testing
  • Full System Testing
• Performance Testing
  • Automated Benchmarks
  • Load Testing
  • Memory Testing
  • Stress Testing
• Security Testing
  • Fuzz Testing
  • Security Boundary Testing
  • Input Validation Testing
• Test Configuration
  • Test Environment Setup
  • Test Data Management
• Continuous Integration
  • GitHub Actions Workflows
    • Main CI Workflow (.github/workflows/ci.yml)
    • Benchmarks Workflow (.github/workflows/benchmarks.yml)
  • CI Jobs Overview
  • Accessing Benchmark Results
  • Test Reporting
• Test Maintenance
  • Test Organization
  • Test Utilities

Testing Philosophy

DaemonEye follows a comprehensive testing strategy that ensures:

• Reliability: Robust error handling and edge case coverage
• Performance: Meets performance requirements under load
• Security: Validates security controls and prevents vulnerabilities
• Maintainability: Easy to understand and modify tests
• Coverage: High test coverage across all components

Testing Strategy

Three-Tier Testing Architecture

1. Unit Tests: Test individual components in isolation
2. Integration Tests: Test component interactions and data flow
3. End-to-End Tests: Test complete workflows and user scenarios

Testing Pyramid

        ┌─────────────────┐
        │   E2E Tests     │  ← Few, slow, expensive
        │   (Manual)      │
        ├─────────────────┤
        │ Integration     │  ← Some, medium speed
        │ Tests           │
        ├─────────────────┤
        │   Unit Tests    │  ← Many, fast, cheap
        │   (Automated)   │
        └─────────────────┘

Unit Testing

Core Testing Framework

DaemonEye uses a comprehensive unit testing framework:

#[cfg(test)]
mod tests {
    use super::*;
    use insta::assert_snapshot;
    use tempfile::TempDir;

    #[tokio::test]
    async fn test_process_collection() {
        let collector = ProcessCollector::new();
        let processes = collector.collect_processes().await.unwrap();

        assert!(!processes.is_empty());
        assert!(processes.iter().any(|p| p.pid > 0));
    }

    #[tokio::test]
    async fn test_database_operations() {
        let temp_dir = TempDir::new().unwrap();
        let db_path = temp_dir.path().join("test.db");

        let db = Database::new(&db_path).await.unwrap();
        let process = ProcessInfo {
            pid: 1234,
            name: "test_process".to_string(),
            // ... other fields
        };

        db.insert_process(&process).await.unwrap();
        let retrieved = db.get_process(1234).await.unwrap();

        assert_eq!(process.pid, retrieved.pid);
        assert_eq!(process.name, retrieved.name);
    }
}

Mocking and Test Doubles

Use mocks for external dependencies:

use mockall::mock;

mock! {
    pub ProcessCollector {}

    #[async_trait]
    impl ProcessCollectionService for ProcessCollector {
        async fn collect_processes(&self) -> Result<CollectionResult, CollectionError>;
        async fn get_system_info(&self) -> Result<SystemInfo, CollectionError>;
    }
}

#[tokio::test]
async fn test_agent_with_mock_collector() {
    let mut mock_collector = MockProcessCollector::new();
    mock_collector
        .expect_collect_processes()
        .times(1)
        .returning(|| Ok(CollectionResult::default()));

    let agent = daemoneye_agent::new(Box::new(mock_collector));
    let result = agent.run_collection_cycle().await;

    assert!(result.is_ok());
}

Property-Based Testing

Use property-based testing for complex logic:

use proptest::prelude::*;

proptest! {
    #[test]
    fn test_process_info_serialization(process in any::<ProcessInfo>()) {
        let serialized = serde_json::to_string(&process).unwrap();
        let deserialized: ProcessInfo = serde_json::from_str(&serialized).unwrap();
        assert_eq!(process, deserialized);
    }

    #[test]
    fn test_sql_query_validation(query in "[a-zA-Z0-9_\\s]+") {
        let result = validate_sql_query(&query);
        // Property: validation should not panic
        let _ = result;
    }
}

Integration Testing

Database Integration Tests

Test database operations with real SQLite:

#[tokio::test]
async fn test_database_integration() {
    let temp_dir = TempDir::new().unwrap();
    let db_path = temp_dir.path().join("integration_test.db");

    let db = Database::new(&db_path).await.unwrap();

    // Test schema creation
    db.create_schema().await.unwrap();

    // Test data insertion
    let process = ProcessInfo {
        pid: 1234,
        name: "test_process".to_string(),
        executable_path: Some("/usr/bin/test".to_string()),
        command_line: Some("test --arg value".to_string()),
        start_time: Some(Utc::now()),
        cpu_usage: Some(0.5),
        memory_usage: Some(1024),
        status: ProcessStatus::Running,
        executable_hash: Some("abc123".to_string()),
        collection_time: Utc::now(),
    };

    db.insert_process(&process).await.unwrap();

    // Test data retrieval
    let retrieved = db.get_process(1234).await.unwrap();
    assert_eq!(process.pid, retrieved.pid);

    // Test query execution
    let results = db
        .query_processes("SELECT * FROM processes WHERE pid = ?", &[1234])
        .await
        .unwrap();
    assert_eq!(results.len(), 1);
}

IPC Integration Tests

Test inter-process communication:

#[tokio::test]
async fn test_ipc_communication() {
    let temp_dir = TempDir::new().unwrap();
    let socket_path = temp_dir.path().join("test.sock");

    // Start server
    let server = IpcServer::new(&socket_path).await.unwrap();
    let server_handle = tokio::spawn(async move { server.run().await });

    // Wait for server to start
    tokio::time::sleep(Duration::from_millis(100)).await;

    // Connect client
    let client = IpcClient::new(&socket_path).await.unwrap();

    // Test request/response
    let request = IpcRequest::CollectProcesses;
    let response = client.send_request(request).await.unwrap();

    assert!(matches!(response, IpcResponse::Processes(_)));

    // Cleanup
    server_handle.abort();
}

Alert Delivery Integration Tests

Test alert delivery mechanisms:

#[tokio::test]
async fn test_alert_delivery() {
    let mut alert_manager = AlertManager::new();

    // Add test sinks
    let syslog_sink = SyslogSink::new("daemon").unwrap();
    let webhook_sink = WebhookSink::new("http://localhost:8080/webhook").unwrap();

    alert_manager.add_sink(Box::new(syslog_sink));
    alert_manager.add_sink(Box::new(webhook_sink));

    // Create test alert
    let alert = Alert {
        id: Uuid::new_v4(),
        rule_name: "test_rule".to_string(),
        severity: AlertSeverity::High,
        message: "Test alert".to_string(),
        process: ProcessInfo::default(),
        timestamp: Utc::now(),
        metadata: HashMap::new(),
    };

    // Send alert
    let result = alert_manager.send_alert(alert).await;
    assert!(result.is_ok());
}

End-to-End Testing

CLI Testing

Test command-line interface:

use insta::assert_snapshot;
use std::process::Command;

#[test]
fn test_cli_help() {
    let mut cmd = Command::cargo_bin("daemoneye-cli").unwrap();
    cmd.assert()
        .success()
        .stdout(predicate::str::contains("DaemonEye CLI"));
}

#[test]
fn test_cli_query() {
    let mut cmd = Command::cargo_bin("daemoneye-cli").unwrap();
    cmd.args(&["query", "SELECT * FROM processes LIMIT 1"])
        .assert()
        .success();
}

#[test]
fn test_cli_config() {
    let mut cmd = Command::cargo_bin("daemoneye-cli").unwrap();
    cmd.args(&["config", "show"])
        .assert()
        .success()
        .stdout(predicate::str::contains("app:"));
}

Full System Testing

Test complete system workflows:

#[tokio::test]
async fn test_full_system_workflow() {
    let temp_dir = TempDir::new().unwrap();
    let config_path = temp_dir.path().join("config.yaml");

    // Create test configuration
    let config = Config::default();
    config.save_to_file(&config_path).unwrap();

    // Start procmond
    let procmond_handle = tokio::spawn(async move {
        let procmond = ProcMonD::new(&config_path).await.unwrap();
        procmond.run().await
    });

    // Start daemoneye-agent
    let agent_handle = tokio::spawn(async move {
        let agent = daemoneye_agent::new(&config_path).await.unwrap();
        agent.run().await
    });

    // Wait for services to start
    tokio::time::sleep(Duration::from_secs(2)).await;

    // Test CLI operations
    let mut cmd = Command::cargo_bin("daemoneye-cli").unwrap();
    cmd.args(&[
        "--config",
        config_path.to_str().unwrap(),
        "query",
        "SELECT COUNT(*) FROM processes",
    ])
    .assert()
    .success();

    // Cleanup
    procmond_handle.abort();
    agent_handle.abort();
}

Performance Testing

Automated Benchmarks

DaemonEye provides a dedicated benchmarking workflow for performance testing:

• Manual Trigger: Performance benchmarks are triggered manually via workflow_dispatch
• Configurable Suites: Select which benchmark suite to run (“all”, “performance_benchmarks”, or “process_collector_benchmarks”)
• Regression Detection: Tests detect performance regressions and log warnings for review
• Baseline Comparison: Benchmark results are cached and compared against baseline from the main branch
• Load Testing: Automated load tests validate system behavior under stress in a separate job
• Results Archival: Benchmark and load test results are uploaded as artifacts with 30-day retention

Developers can access benchmark results from the GitHub Actions workflow artifacts. Performance regressions are logged as warnings but do not fail the build, allowing for manual review and assessment.

Load Testing

Test system performance under load:

use criterion::{Criterion, black_box, criterion_group, criterion_main};

fn benchmark_process_collection(c: &mut Criterion) {
    let mut group = c.benchmark_group("process_collection");

    group.bench_function("collect_processes", |b| {
        b.iter(|| {
            let collector = ProcessCollector::new();
            black_box(collector.collect_processes())
        })
    });

    group.bench_function("collect_processes_parallel", |b| {
        b.iter(|| {
            let collector = ProcessCollector::new();
            black_box(collector.collect_processes_parallel())
        })
    });

    group.finish();
}

fn benchmark_database_operations(c: &mut Criterion) {
    let mut group = c.benchmark_group("database_operations");

    group.bench_function("insert_process", |b| {
        let db = Database::new(":memory:").unwrap();
        let process = ProcessInfo::default();

        b.iter(|| black_box(db.insert_process(&process)))
    });

    group.bench_function("query_processes", |b| {
        let db = Database::new(":memory:").unwrap();
        // Insert test data
        for i in 0..1000 {
            let process = ProcessInfo {
                pid: i,
                ..Default::default()
            };
            db.insert_process(&process).unwrap();
        }

        b.iter(|| black_box(db.query_processes("SELECT * FROM processes WHERE pid > ?", &[500])))
    });

    group.finish();
}

criterion_group!(
    benches,
    benchmark_process_collection,
    benchmark_database_operations
);
criterion_main!(benches);

Memory Testing

Test memory usage and leaks:

#[tokio::test]
async fn test_memory_usage() {
    let initial_memory = get_memory_usage();

    // Run operations that should not leak memory
    for _ in 0..1000 {
        let collector = ProcessCollector::new();
        let _processes = collector.collect_processes().await.unwrap();
        drop(collector);
    }

    // Force garbage collection
    tokio::task::yield_now().await;

    let final_memory = get_memory_usage();
    let memory_increase = final_memory - initial_memory;

    // Memory increase should be minimal
    assert!(memory_increase < 10 * 1024 * 1024); // 10MB
}

fn get_memory_usage() -> usize {
    // Platform-specific memory usage detection
    #[cfg(target_os = "linux")]
    {
        let status = std::fs::read_to_string("/proc/self/status").unwrap();
        for line in status.lines() {
            if line.starts_with("VmRSS:") {
                let parts: Vec<&str> = line.split_whitespace().collect();
                return parts[1].parse::<usize>().unwrap() * 1024; // Convert to bytes
            }
        }
        0
    }
    #[cfg(not(target_os = "linux"))]
    {
        // Fallback for other platforms
        0
    }
}

Stress Testing

Test system behavior under stress:

#[tokio::test]
async fn test_stress_collection() {
    let collector = ProcessCollector::new();

    // Run collection continuously for 60 seconds
    let start = Instant::now();
    let mut count = 0;

    while start.elapsed() < Duration::from_secs(60) {
        let processes = collector.collect_processes().await.unwrap();
        count += processes.len();

        // Small delay to prevent overwhelming the system
        tokio::time::sleep(Duration::from_millis(100)).await;
    }

    // Should have collected a reasonable number of processes
    assert!(count > 0);
    println!("Collected {} processes in 60 seconds", count);
}

Security Testing

Fuzz Testing

Test with random inputs:

use cargo_fuzz;

#[no_mangle]
pub extern "C" fn fuzz_process_info(data: &[u8]) {
    if let Ok(process_info) = ProcessInfo::from_bytes(data) {
        // Test that deserialization doesn't panic
        let _ = process_info.pid;
        let _ = process_info.name;
    }
}

#[no_mangle]
pub extern "C" fn fuzz_sql_query(data: &[u8]) {
    if let Ok(query) = std::str::from_utf8(data) {
        // Test SQL query validation
        let _ = validate_sql_query(query);
    }
}

Security Boundary Testing

Test security boundaries:

#[tokio::test]
async fn test_privilege_dropping() {
    let collector = ProcessCollector::new();

    // Should start with elevated privileges
    assert!(collector.has_privileges());

    // Drop privileges
    collector.drop_privileges().await.unwrap();

    // Should no longer have privileges
    assert!(!collector.has_privileges());

    // Should still be able to collect processes (with reduced capabilities)
    let processes = collector.collect_processes().await.unwrap();
    assert!(!processes.is_empty());
}

#[tokio::test]
async fn test_sql_injection_prevention() {
    let db = Database::new(":memory:").unwrap();

    // Test various SQL injection attempts
    let malicious_queries = vec![
        "'; DROP TABLE processes; --",
        "1' OR '1'='1",
        "'; INSERT INTO processes VALUES (9999, 'hacker', '/bin/evil'); --",
    ];

    for query in malicious_queries {
        let result = db.execute_query(query).await;
        // Should either reject the query or sanitize it safely
        match result {
            Ok(_) => {
                // If query succeeds, verify no damage was done
                let count = db.count_processes().await.unwrap();
                assert_eq!(count, 0); // No processes should exist
            }
            Err(_) => {
                // Query was rejected, which is also acceptable
            }
        }
    }
}

Input Validation Testing

Test input validation:

#[test]
fn test_input_validation() {
    // Test valid inputs
    let valid_process = ProcessInfo {
        pid: 1234,
        name: "valid_process".to_string(),
        executable_path: Some("/usr/bin/valid".to_string()),
        command_line: Some("valid --arg value".to_string()),
        start_time: Some(Utc::now()),
        cpu_usage: Some(0.5),
        memory_usage: Some(1024),
        status: ProcessStatus::Running,
        executable_hash: Some("abc123".to_string()),
        collection_time: Utc::now(),
    };

    assert!(valid_process.validate().is_ok());

    // Test invalid inputs
    let invalid_process = ProcessInfo {
        pid: 0,                                            // Invalid PID
        name: "".to_string(),                              // Empty name
        executable_path: Some("".to_string()),             // Empty path
        command_line: Some("a".repeat(10000).to_string()), // Too long
        start_time: Some(Utc::now()),
        cpu_usage: Some(-1.0), // Negative CPU usage
        memory_usage: Some(0),
        status: ProcessStatus::Running,
        executable_hash: Some("invalid_hash".to_string()),
        collection_time: Utc::now(),
    };

    assert!(invalid_process.validate().is_err());
}

Test Configuration

Test Environment Setup

# test-config.yaml
app:
  log_level: debug
  scan_interval_ms: 1000
  batch_size: 10

database:
  path: ':memory:'
  max_connections: 5
  retention_days: 1

alerting:
  enabled: false

testing:
  enable_mocks: true
  mock_external_services: true
  test_data_dir: /tmp/daemoneye-test
  cleanup_after_tests: true

Test Data Management

pub struct TestDataManager {
    temp_dir: TempDir,
    test_data: HashMap<String, Vec<u8>>,
}

impl TestDataManager {
    pub fn new() -> Self {
        Self {
            temp_dir: TempDir::new().unwrap(),
            test_data: HashMap::new(),
        }
    }

    pub fn add_test_data(&mut self, name: &str, data: &[u8]) {
        self.test_data.insert(name.to_string(), data.to_vec());
    }

    pub fn get_test_data(&self, name: &str) -> Option<&[u8]> {
        self.test_data.get(name).map(|v| v.as_slice())
    }

    pub fn create_test_database(&self) -> PathBuf {
        let db_path = self.temp_dir.path().join("test.db");
        let db = Database::new(&db_path).unwrap();
        db.create_schema().unwrap();
        db_path
    }
}

Continuous Integration

GitHub Actions Workflows

DaemonEye uses two separate GitHub Actions workflows for testing:

Main CI Workflow (.github/workflows/ci.yml)

The main CI pipeline runs on every push and pull request:

name: Tests

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: jdx/mise-action@v3
        with:
          install: true
          cache: true
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Ensure rustfmt and clippy are installed
        run: rustup component add rustfmt clippy

      - name: Check formatting
        run: just lint-rust

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: jdx/mise-action@v3
        with:
          install: true
          cache: true
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Run tests (all features)
        run: mise x -- cargo nextest run --profile ci --all-features

      - name: Build release
        run: mise x -- cargo build --release --all-features

  test-cross-platform:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    needs: quality
    steps:
      - uses: actions/checkout@v6
      - uses: jdx/mise-action@v3
        with:
          install: true
          cache: true
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - run: mise x -- cargo nextest run --profile ci --all-features
      - run: mise x -- cargo build --release --all-features

  coverage:
    runs-on: ubuntu-latest
    needs: [test, test-cross-platform, quality]
    steps:
      - uses: actions/checkout@v6
      - uses: jdx/mise-action@v3
        with:
          install: true
          cache: true
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Generate coverage
        run: mise x -- cargo llvm-cov --all-features --no-report

      - name: Combine coverage reports
        run: mise x -- cargo llvm-cov report --lcov --output-path lcov.info

      - name: Upload to Codecov
        uses: codecov/codecov-action@v5
        with:
          files: lcov.info
          fail_ci_if_error: false
          token: ${{ secrets.CODECOV_TOKEN }}

Benchmarks Workflow (.github/workflows/benchmarks.yml)

The benchmarks workflow is triggered manually and runs independently:

name: Benchmarks

on:
  workflow_dispatch:
    inputs:
      suite:
        description: Benchmark suite to run
        required: false
        default: all
        type: choice
        options:
          - all
          - performance_benchmarks
          - process_collector_benchmarks

jobs:
  benchmarks:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: jdx/mise-action@v3
        with:
          install: true
          cache: true
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Restore baseline benchmarks
        uses: actions/cache/restore@v4
        with:
          path: target/criterion
          key: criterion-baseline-${{ runner.os }}

      - name: Run benchmarks
        env:
          BENCH_SUITE: ${{ inputs.suite }}
        run: |
          if [ "$BENCH_SUITE" = "all" ]; then
            mise x -- cargo bench --package procmond 2>&1 | tee bench-output.txt
          else
            mise x -- cargo bench --package procmond --bench "$BENCH_SUITE" 2>&1 | tee bench-output.txt
          fi

      - name: Check for performance regression
        run: |
          if grep -q "Performance has regressed" bench-output.txt; then
            echo "::warning::Performance regression detected in benchmarks"
            grep -A2 "Performance has regressed" bench-output.txt
          else
            echo "No performance regressions detected"
          fi

      - name: Save baseline benchmarks
        uses: actions/cache/save@v4
        if: github.ref == 'refs/heads/main'
        with:
          path: target/criterion
          key: criterion-baseline-${{ runner.os }}

      - name: Upload benchmark results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: benchmark-results
          path: bench-output.txt
          retention-days: 30

  load-tests:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v6

      - uses: jdx/mise-action@v3
        with:
          install: true
          cache: true
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Run load tests
        run: NO_COLOR=1 TERM=dumb mise x -- cargo test --package procmond --test
          load_tests -- --ignored --nocapture 2>&1 | tee load-test-output.txt

      - name: Upload load test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: load-test-results
          path: load-test-output.txt
          retention-days: 30

CI Jobs Overview

The main CI pipeline includes the following jobs:

1. quality: Runs code formatting and linting checks
2. test: Executes the full test suite with all features enabled
3. test-cross-platform: Tests on Ubuntu, macOS, and Windows
4. coverage: Generates and uploads code coverage reports

The benchmarks workflow includes two independent jobs:

1. benchmarks: Runs performance benchmarks with configurable suite selection (15-minute timeout)
2. load-tests: Runs load tests under stress conditions (10-minute timeout)

Accessing Benchmark Results

Benchmark results are available through the dedicated benchmarks workflow:

• Manual Trigger: Navigate to the Actions tab and select the “Benchmarks” workflow, then choose “Run workflow” to trigger manually
• Suite Selection: Choose which benchmark suite to run: “all” (default), “performance_benchmarks”, or “process_collector_benchmarks”
• Workflow Artifacts: Download benchmark-results and load-test-results artifacts from the workflow summary page
• CI Logs: View benchmark output directly in the workflow logs
• Performance Alerts: Regressions are logged as warnings for manual review without failing the workflow

The benchmarks workflow stores baseline results from the main branch and compares all subsequent runs against this baseline to detect performance regressions.

Test Reporting

use insta::assert_snapshot;

#[test]
fn test_config_serialization() {
    let config = Config::default();
    let serialized = serde_yaml::to_string(&config).unwrap();

    // Snapshot testing for configuration
    assert_snapshot!(serialized);
}

#[test]
fn test_alert_format() {
    let alert = Alert {
        id: Uuid::parse_str("123e4567-e89b-12d3-a456-426614174000").unwrap(),
        rule_name: "test_rule".to_string(),
        severity: AlertSeverity::High,
        message: "Test alert message".to_string(),
        process: ProcessInfo::default(),
        timestamp: Utc::now(),
        metadata: HashMap::new(),
    };

    let formatted = alert.format_json().unwrap();
    assert_snapshot!(formatted);
}

Test Maintenance

Test Organization

// tests/
// ├── unit/
// │   ├── collector_tests.rs
// │   ├── database_tests.rs
// │   └── alert_tests.rs
// ├── integration/
// │   ├── ipc_tests.rs
// │   ├── database_tests.rs
// │   └── alert_delivery_tests.rs
// ├── e2e/
// │   ├── cli_tests.rs
// │   └── system_tests.rs
// └── common/
//     ├── test_helpers.rs
//     └── test_data.rs

Test Utilities

// tests/common/test_helpers.rs
pub struct TestHelper {
    temp_dir: TempDir,
    config: Config,
}

impl TestHelper {
    pub fn new() -> Self {
        let temp_dir = TempDir::new().unwrap();
        let config = Config::default();

        Self { temp_dir, config }
    }

    pub fn create_test_database(&self) -> Database {
        let db_path = self.temp_dir.path().join("test.db");
        Database::new(&db_path).unwrap()
    }

    pub fn create_test_config(&self) -> PathBuf {
        let config_path = self.temp_dir.path().join("config.yaml");
        self.config.save_to_file(&config_path).unwrap();
        config_path
    }

    pub fn cleanup(&self) {
        // Cleanup test resources
    }
}

impl Drop for TestHelper {
    fn drop(&mut self) {
        self.cleanup();
    }
}

This testing documentation provides comprehensive guidance for testing DaemonEye. For additional testing information, consult the specific test files or contact the development team.

Contributing to DaemonEye

Thank you for your interest in contributing to DaemonEye! This guide will help you get started with contributing to the project.

Table of Contents

• Getting Started
  • Prerequisites
  • Fork and Clone
  • Development Setup
• Development Environment
  • Project Structure
  • Workspace Configuration
  • Development Commands
  • Commit Signing and GPG Setup
    • Troubleshooting
• Code Standards
  • Rust Standards
  • Code Style
  • Naming Conventions
  • Documentation Standards
• Testing Requirements
  • Test Coverage
  • Test Structure
  • Running Tests
• Pull Request Process
  • Before Submitting
  • Commit Message Format
    • Types
    • Examples
  • Pull Request Guidelines
  • Pull Request Template
• Issue Reporting
  • Bug Reports
  • Feature Requests
  • Issue Templates
• Documentation
  • Documentation Standards
  • Documentation Structure
  • Building Documentation
• Community Guidelines
  • Code of Conduct
  • Communication
  • Recognition
• Development Workflow
  • Branch Strategy
  • Release Process
  • Continuous Integration
• Getting Help
• License

Getting Started

Prerequisites

Before contributing to DaemonEye, ensure you have:

• Rust 1.91+: Latest stable Rust toolchain
• Git: Version control system
• Docker: For containerized testing (optional)
• Just: Task runner (install with cargo install just)
• Editor: VS Code with Rust extension (recommended)

Fork and Clone

1. Fork the repository on GitHub

2. Clone your fork locally:

   git clone https://github.com/your-username/daemoneye.git
   cd daemoneye
   

3. Add the upstream repository:

   git remote add upstream https://github.com/EvilBit-Labs/daemoneye.git
   

Development Setup

1. Install dependencies:

   just setup
   

2. Run tests to ensure everything works:

   just test
   

3. Build the project:

   just build
   

Development Environment

Project Structure

DaemonEye/
├── procmond/           # Process monitoring daemon
├── daemoneye-agent/      # Agent orchestrator
├── daemoneye-cli/        # CLI interface
├── daemoneye-lib/       # Shared library
├── docs/               # Documentation
├── tests/              # Integration tests
├── examples/           # Example configurations
├── justfile            # Task runner
├── Cargo.toml          # Workspace configuration
└── README.md           # Project README

Workspace Configuration

DaemonEye uses a Cargo workspace with the following structure:

[workspace]
resolver = "2"
members = [
  "procmond",
  "daemoneye-agent",
  "daemoneye-cli",
  "daemoneye-lib",
]

[workspace.dependencies]
tokio = { version = "1.0", features = ["full"] }
clap = { version = "4.6.0", features = ["derive", "completion"] }
serde = { version = "1.0", features = ["derive"] }
sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "sqlite"] }
sysinfo = "0.38.4"
tracing = "0.1"
thiserror = "1.0"
anyhow = "1.0"

Development Commands

Use the just task runner for common development tasks:

# Setup development environment
just setup

# Build the project
just build

# Run tests
just test

# Run linting
just lint

# Format code
just fmt

# Run benchmarks
just bench

# Run procmond benchmarks
just bench-procmond

# Generate documentation
just docs

# Clean build artifacts
just clean

Commit Signing and GPG Setup

Workspace tooling enforces signed commits (git.enableCommitSigning) and a rebase-first sync strategy. Configure GPG before making changes to avoid commit failures.

1. Install GnuPG

   • macOS: brew install gnupg pinentry-mac
   • Linux: install gnupg and an appropriate pinentry package via your package manager
   • Windows: install Gpg4win and enable the GPG Agent during setup

2. Generate a signing key (4096-bit RSA recommended)

   gpg --full-generate-key
   

   Choose RSA and RSA, key size 4096, set an expiration (or none), and provide your name and email that matches the user.email configured for Git.

3. Locate the long key ID

   gpg --list-secret-keys --keyid-format=long
   

   Copy the 16-character key ID that appears after sec rsa4096/.

4. Export the public key for review systems

   gpg --armor --export <KEY_ID> > ~/.gnupg/daemoneye.pub
   

   Upload this armored key to GitHub (Settings → SSH and GPG keys) and any internal key servers used by your organization.

5. Configure Git to sign by default

   git config --global user.signingkey <KEY_ID>
   git config --global commit.gpgsign true
   git config --global tag.gpgsign true
   git config --global gpg.program $(command -v gpg)
   

   If the workspace settings conflict with per-repo preferences, create a project-local override via .git/config after following the required steps.

6. Ensure the GPG agent is active

   • macOS: add pinentry-program /opt/homebrew/bin/pinentry-mac to ~/.gnupg/gpg-agent.conf, then run gpgconf --kill gpg-agent
   • Windows: restart the “GnuPG Agent” service from the Gpg4win config utility
   • Linux: ensure gpg-agent starts from your desktop session (eval "$(gpg-agent --daemon)" in shell profile if necessary)

7. Verify signing works

   echo "test" | gpg --clearsign
   git commit --allow-empty -S -m "test: verify signing"
   

   If prompted for a passphrase, select “save in keychain/keyring” so future commits succeed from VS Code as well as the CLI.

Troubleshooting

• gpg: signing failed: No secret key — confirm the key ID in git config matches gpg --list-secret-keys
• gpg: signing failed: Inappropriate ioctl for device — configure an appropriate pinentry program and restart gpg-agent
• Emergency opt-out (e.g., broken key) — run git config commit.gpgsign false locally and notify the maintainers; automated pipelines still require signatures for merged commits.

These steps ensure developers understand the enforced workflow before VS Code rejects unsigned commits. Refer back to this section any time a workstation is rebuilt.

Code Standards

Rust Standards

DaemonEye follows strict Rust coding standards:

1. Edition: Always use Rust 2024 Edition
2. Linting: Zero warnings policy with cargo clippy -- -D warnings
3. Safety: unsafe_code = "forbid" enforced at workspace level
4. Formatting: Standard rustfmt with 119 character line length
5. Error Handling: Use thiserror for structured errors, anyhow for error context

Code Style

// Use thiserror for library errors
#[derive(Debug, Error)]
pub enum CollectionError {
    #[error("Permission denied accessing process {pid}")]
    PermissionDenied { pid: u32 },

    #[error("Process {pid} no longer exists")]
    ProcessNotFound { pid: u32 },

    #[error("I/O error: {0}")]
    IoError(#[from] std::io::Error),

    #[error("No processes were collected")]
    NoProcessesCollected,
}

// Use anyhow for application error context
use anyhow::{Context, Result};

// Helper function to validate collected process data
fn validate_process_data(processes: &[ProcessInfo]) -> Result<(), CollectionError> {
    if processes.is_empty() {
        return Err(CollectionError::NoProcessesCollected);
    }

    // Additional validation logic could go here
    // For example: checking for required fields, data integrity, etc.
    Ok(())
}

pub async fn collect_processes() -> Result<Vec<ProcessInfo>, CollectionError> {
    let mut system = sysinfo::System::new_all();
    system.refresh_all();

    let processes = system
        .processes()
        .values()
        .map(|p| ProcessInfo::from(p))
        .collect::<Vec<_>>();

    // Validate collected data before returning
    validate_process_data(&processes)?;

    Ok(processes)
}

// Document all public APIs
/// Collects information about all running processes.
///
/// # Returns
///
/// A vector of `ProcessInfo` structs containing details about each process.
///
/// # Errors
///
/// This function will return an error if:
/// - System information cannot be accessed
/// - Process enumeration fails
/// - No processes could be collected from the system
/// - Memory allocation fails
///
/// # Examples
///
/// ```rust
/// use daemoneye_lib::collector::ProcessCollector;
///
/// let collector = ProcessCollector::new();
/// let processes = collector.collect_processes().await?;
/// println!("Found {} processes", processes.len());
/// ```
pub async fn collect_processes() -> Result<Vec<ProcessInfo>, CollectionError> {
    // Implementation
}

Naming Conventions

• Functions: snake_case
• Variables: snake_case
• Types: PascalCase
• Constants: SCREAMING_SNAKE_CASE
• Modules: snake_case
• Files: snake_case.rs

Documentation Standards

All public APIs must be documented with rustdoc comments:

/// A process information structure containing details about a running process.
///
/// This structure provides comprehensive information about a process including
/// its PID, name, executable path, command line arguments, and resource usage.
///
/// # Examples
///
/// ```rust
/// use daemoneye_lib::ProcessInfo;
///
/// let process = ProcessInfo {
///     pid: 1234,
///     name: "example".to_string(),
///     executable_path: Some("/usr/bin/example".to_string()),
///     command_line: Some("example --arg value".to_string()),
///     start_time: Some(Utc::now()),
///     cpu_usage: Some(0.5),
///     memory_usage: Some(1024),
///     status: ProcessStatus::Running,
///     executable_hash: Some("abc123".to_string()),
///     collection_time: Utc::now(),
/// };
/// ```
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct ProcessInfo {
    /// The process ID (PID) of the process
    pub pid: u32,

    /// The name of the process
    pub name: String,

    /// The full path to the process executable
    pub executable_path: Option<String>,

    /// The command line arguments used to start the process
    pub command_line: Option<String>,

    /// The time when the process was started
    pub start_time: Option<DateTime<Utc>>,

    /// The current CPU usage percentage
    pub cpu_usage: Option<f64>,

    /// The current memory usage in bytes
    pub memory_usage: Option<u64>,

    /// The current status of the process
    pub status: ProcessStatus,

    /// The SHA-256 hash of the process executable
    pub executable_hash: Option<String>,

    /// The time when this information was collected
    pub collection_time: DateTime<Utc>,
}

Testing Requirements

Test Coverage

All code must have comprehensive test coverage:

• Unit Tests: Test individual functions and methods
• Integration Tests: Test component interactions
• End-to-End Tests: Test complete workflows
• Property Tests: Test with random inputs
• Fuzz Tests: Test with malformed inputs

Test Structure

#[cfg(test)]
mod tests {
    use super::*;
    use insta::assert_snapshot;
    use tempfile::TempDir;

    #[tokio::test]
    async fn test_process_collection() {
        let collector = ProcessCollector::new();
        let processes = collector.collect_processes().await.unwrap();

        assert!(!processes.is_empty());
        assert!(processes.iter().any(|p| p.pid > 0));
    }

    #[test]
    fn test_process_info_serialization() {
        let process = ProcessInfo::default();
        let serialized = serde_json::to_string(&process).unwrap();
        let deserialized: ProcessInfo = serde_json::from_str(&serialized).unwrap();
        assert_eq!(process, deserialized);
    }
}

Running Tests

# Run all tests
cargo test

# Run specific test
cargo test test_process_collection

# Run tests with output
cargo test -- --nocapture

# Run integration tests
cargo test --test integration

# Run benchmarks
cargo bench

# Run fuzz tests
cargo fuzz run process_info

Pull Request Process

Before Submitting

1. Sync with upstream:

   git fetch upstream
   git checkout main
   git merge upstream/main
   

2. Create a feature branch:

   git checkout -b feature/your-feature-name
   

3. Make your changes:

   • Write code following the coding standards
   • Add comprehensive tests
   • Update documentation
   • Run all tests and linting

4. Commit your changes:

   git add .
   git commit -m "feat: add new feature description"
   

Commit Message Format

Use conventional commits format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test changes
• chore: Build process or auxiliary tool changes

Examples

feat(collector): add process filtering by name

Add ability to filter processes by name pattern using regex.
This improves performance when monitoring specific processes.

Closes #123

fix(database): resolve memory leak in query execution

Fix memory leak that occurred when executing large queries.
The issue was caused by not properly cleaning up prepared statements.

Fixes #456

Pull Request Guidelines

1. Title: Clear, descriptive title
2. Description: Detailed description of changes
3. Tests: Ensure all tests pass
4. Documentation: Update relevant documentation
5. Breaking Changes: Clearly mark any breaking changes
6. Related Issues: Link to related issues

Pull Request Template

## Description

Brief description of the changes made.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Testing

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] End-to-end tests pass
- [ ] Manual testing completed
- [ ] Performance tests pass

## Checklist

- [ ] Code follows the project's style guidelines
- [ ] Self-review of code completed
- [ ] Code is properly commented
- [ ] Documentation updated
- [ ] No new warnings introduced
- [ ] Breaking changes documented

## Related Issues

Closes #123
Fixes #456

Issue Reporting

Bug Reports

When reporting bugs, please include:

1. Environment: OS, Rust version, DaemonEye version
2. Steps to Reproduce: Clear, numbered steps
3. Expected Behavior: What should happen
4. Actual Behavior: What actually happens
5. Logs: Relevant log output
6. Screenshots: If applicable

Feature Requests

When requesting features, please include:

1. Use Case: Why is this feature needed?
2. Proposed Solution: How should it work?
3. Alternatives: Other solutions considered
4. Additional Context: Any other relevant information

Issue Templates

Use the provided issue templates:

• Bug Report: .github/ISSUE_TEMPLATE/bug_report.md
• Feature Request: .github/ISSUE_TEMPLATE/feature_request.md
• Question: .github/ISSUE_TEMPLATE/question.md

Documentation

Documentation Standards

• Keep documentation up to date
• Use clear, concise language
• Include code examples
• Follow markdown best practices
• Use consistent formatting

Documentation Structure

docs/
├── src/
│   ├── introduction.md
│   ├── getting-started.md
│   ├── architecture/
│   ├── technical/
│   ├── user-guides/
│   ├── api-reference/
│   ├── deployment/
│   ├── security.md
│   ├── testing.md
│   └── contributing.md
├── book.toml
└── README.md

Building Documentation

# Install mdbook
cargo install mdbook

# Build documentation
mdbook build

# Serve documentation locally
mdbook serve

Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment for all contributors. Please:

• Be respectful and constructive
• Focus on what is best for the community
• Show empathy towards other community members
• Accept constructive criticism gracefully
• Help others learn and grow

Communication

• GitHub Issues: For bug reports and feature requests
• GitHub Discussions: For questions and general discussion
• Pull Requests: For code contributions
• Discord: For real-time chat (invite link in README)

Recognition

Contributors are recognized in:

• CONTRIBUTORS.md file
• Release notes
• Project documentation
• Community highlights

Development Workflow

Branch Strategy

• main: Production-ready code
• develop: Integration branch for features
• feature/*: Feature development branches
• bugfix/*: Bug fix branches
• hotfix/*: Critical bug fixes

Release Process

1. Version Bumping: Update version numbers
2. Changelog: Update CHANGELOG.md
3. Documentation: Update documentation
4. Testing: Run full test suite
5. Release: Create GitHub release
6. Distribution: Publish to package managers

Continuous Integration

All pull requests must pass:

• Unit tests
• Integration tests
• Linting checks
• Security scans
• Performance benchmarks
• Documentation builds

Getting Help

If you need help contributing:

1. Check Documentation: Review this guide and other docs
2. Search Issues: Look for similar issues or discussions
3. Ask Questions: Use GitHub Discussions or Discord
4. Contact Maintainers: Reach out to project maintainers

License

By contributing to DaemonEye, you agree that your contributions will be licensed under the same license as the project (Apache 2.0 for core features, commercial license for business/enterprise features).

Thank you for contributing to DaemonEye! Your contributions help make the project better for everyone.