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#

[TOC]

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:

Request minimal privileges during startup
Drop privileges immediately after initialization
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)#

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

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#

Install Rust (1.91+):

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

Clone and build:

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

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 have DaemonEye running:

Read the Operator Guide for detailed usage instructions
Explore Configuration Guide for advanced configuration
Learn Rule Development for creating custom detection rules
Review Security Architecture for understanding the security model
Check Deployment Guide for production deployment

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.