From 547b47f687877c2a7b411dbcbe578f1871e2b5c1 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Sun, 26 Apr 2026 11:08:15 -0400 Subject: [PATCH 01/11] docs: remove aspirational user-facing docs (install/deployment/operator/API/CLI) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit DaemonEye has not shipped a v1.0.0 release yet, so the user-facing installation, deployment, operator, configuration, API reference, and CLI reference docs in docs/src/ describe features users cannot actually use. Equivalent content is preserved in Confluence space ES (Installation 1802370, Docker 1802371, Kubernetes 1802372, Configuration 1802373/1802375, Core API 1802366, CLI 1802368, plus archived ProcMonD-era operator content) per the open-core hygiene workflow's verify-before-delete rule. Removed: - docs/src/deployment.md and the deployment/ directory - docs/src/user-guides.md and the user-guides/ directory - docs/src/api-reference.md and the api-reference/ directory - docs/src/cli-reference.md (orphaned — never linked from SUMMARY.md) Updated: - docs/src/SUMMARY.md — drop deleted-doc TOC entries - docs/src/introduction.md — trim Documentation Structure / Quick Links / Getting Help sections; replace "Multi-tier Architecture" feature bullet with explicit Community-tier-only boundary acknowledgement - docs/src/getting-started.md — replace Next Steps links to deleted operator/configuration/deployment docs with pointers to surviving architecture/technical/security/contributing sections - docs/src/project-overview.md — fix Next Steps links and add v1.0.0 publication note for operator/configuration guides Local docs/book/pricing.html (orphan mdbook artifact, gitignored) was also removed locally; not part of this commit. Signed-off-by: UncleSp1d3r --- docs/src/SUMMARY.md | 11 - docs/src/api-reference.md | 708 ---------- docs/src/api-reference/core-api.md | 690 ---------- docs/src/cli-reference.md | 406 ------ docs/src/deployment.md | 579 -------- docs/src/deployment/configuration.md | 1095 --------------- docs/src/deployment/docker.md | 1722 ------------------------ docs/src/deployment/installation.md | 759 ----------- docs/src/deployment/kubernetes.md | 1351 ------------------- docs/src/getting-started.md | 13 +- docs/src/introduction.md | 50 +- docs/src/project-overview.md | 10 +- docs/src/user-guides.md | 547 -------- docs/src/user-guides/configuration.md | 617 --------- docs/src/user-guides/operator-guide.md | 812 ----------- 15 files changed, 34 insertions(+), 9336 deletions(-) delete mode 100644 docs/src/api-reference.md delete mode 100644 docs/src/api-reference/core-api.md delete mode 100644 docs/src/cli-reference.md delete mode 100644 docs/src/deployment.md delete mode 100644 docs/src/deployment/configuration.md delete mode 100644 docs/src/deployment/docker.md delete mode 100644 docs/src/deployment/installation.md delete mode 100644 docs/src/deployment/kubernetes.md delete mode 100644 docs/src/user-guides.md delete mode 100644 docs/src/user-guides/configuration.md delete mode 100644 docs/src/user-guides/operator-guide.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index bba6b261..30c93df5 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -15,17 +15,6 @@ - [Windows Process Collector](./technical/windows-process-collector.md) - [Query Pipeline and SQL Dialect](./technical/query-pipeline.md) - [SQL Dialect Quick Reference](./technical/sql-dialect-reference.md) -- [User Guides](./user-guides.md) - - [Operator Guide](./user-guides/operator-guide.md) - - [Configuration Guide](./user-guides/configuration.md) - - [CLI Reference](./user-guides/cli-reference.md) -- [API Reference](./api-reference.md) - - [Core API](./api-reference/core-api.md) -- [Deployment](./deployment.md) - - [Installation](./deployment/installation.md) - - [Configuration](./deployment/configuration.md) - - [Docker](./deployment/docker.md) - - [Kubernetes](./deployment/kubernetes.md) - [Security](./security.md) - [Security Design Overview](./technical/security_design_overview.md) - [Testing](./testing.md) diff --git a/docs/src/api-reference.md b/docs/src/api-reference.md deleted file mode 100644 index f4689abb..00000000 --- a/docs/src/api-reference.md +++ /dev/null @@ -1,708 +0,0 @@ -# API Reference - -This section contains comprehensive API documentation for DaemonEye, covering all public interfaces, data structures, and usage examples. - -## Core API - -The core API provides the fundamental interfaces for process monitoring, alerting, and data management. - -[Read Core API Documentation →](./api-reference/core-api.md) - -## API Overview - -### Component APIs - -DaemonEye provides APIs for each component: - -- **ProcMonD API**: Process collection and system monitoring -- **daemoneye-agent API**: Alerting and orchestration -- **daemoneye-cli API**: Command-line interface and management -- **daemoneye-lib API**: Shared library interfaces - -### API Design Principles - -1. **Async-First**: All APIs use async/await patterns -2. **Error Handling**: Structured error types with `thiserror` -3. **Type Safety**: Strong typing with Rust's type system -4. **Documentation**: Comprehensive rustdoc comments -5. **Examples**: Code examples for all public APIs - -## Quick Reference - -### Process Collection - -```rust,ignore -use daemoneye_lib::collector::ProcessCollector; - -async fn collect_processes() -> Result<(), Box> { - let collector = ProcessCollector::new(); - let processes = collector.collect_processes().await?; - Ok(()) -} -``` - -### Database Operations - -```rust,ignore -use daemoneye_lib::storage::Database; - -async fn database_operations() -> Result<(), Box> { - let db = Database::new("processes.db").await?; - let pid = 1234; - let processes = db - .query_processes("SELECT * FROM processes WHERE pid = ?", &[&pid]) - .await?; - Ok(()) -} -``` - -### Alert Management - -```rust,ignore -use daemoneye_lib::alerting::{Alert, AlertManager, AlertSeverity}; -use daemoneye_lib::models::ProcessInfo; - -async fn alert_management() -> Result<(), Box> { - let mut alert_manager = AlertManager::new(); - alert_manager.add_sink(Box::new(SyslogSink::new("daemon")?)); - - // Create a sample alert - let alert = Alert::new( - "suspicious_process_detected", - "Process 'malware.exe' detected with suspicious behavior", - AlertSeverity::High, - Some(ProcessInfo { - pid: 1234, - name: "malware.exe".to_string(), - executable_path: Some("/tmp/malware.exe".to_string()), - ..Default::default() - }), - ); - - alert_manager.send_alert(alert).await?; - Ok(()) -} -``` - -### Configuration Management - -```rust,ignore -use daemoneye_lib::config::Config; - -async fn configuration_management() -> Result<(), Box> { - let config = Config::load_from_file("config.yaml").await?; - let scan_interval = config.get::("app.scan_interval_ms")?; - Ok(()) -} -``` - -## Data Structures - -### ProcessInfo - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub struct ProcessInfo { - pub pid: u32, - pub name: String, - pub executable_path: Option, - pub command_line: Option, - pub start_time: Option>, - pub cpu_usage: Option, - pub memory_usage: Option, - pub status: ProcessStatus, - pub executable_hash: Option, - pub collection_time: DateTime, -} -``` - -### Alert - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub struct Alert { - pub id: Uuid, - pub rule_name: String, - pub severity: AlertSeverity, - pub message: String, - pub process: ProcessInfo, - pub timestamp: DateTime, - pub metadata: HashMap, -} -``` - -### DetectionRule - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub struct DetectionRule { - pub name: String, - pub description: String, - pub sql_query: String, - pub priority: u32, - pub enabled: bool, - pub created_at: DateTime, - pub updated_at: DateTime, -} -``` - -## Error Types - -### CollectionError - -```rust,ignore -#[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("System error: {0}")] - SystemError(String), -} -``` - -### DatabaseError - -```rust,ignore -#[derive(Debug, Error)] -pub enum DatabaseError { - #[error("Database connection failed: {0}")] - ConnectionFailed(String), - - #[error("Query execution failed: {0}")] - QueryFailed(String), - - #[error("Transaction failed: {0}")] - TransactionFailed(String), - - #[error("SQLite error: {0}")] - SqliteError(#[from] rusqlite::Error), -} -``` - -### AlertError - -```rust,ignore -#[derive(Debug, Error)] -pub enum AlertError { - #[error("Alert delivery failed: {0}")] - DeliveryFailed(String), - - #[error("Invalid alert format: {0}")] - InvalidFormat(String), - - #[error("Alert sink error: {0}")] - SinkError(String), - - #[error("Alert queue full")] - QueueFull, -} -``` - -## Service Traits - -### ProcessCollectionService - -```rust,ignore -#[async_trait] -pub trait ProcessCollectionService: Send + Sync { - async fn collect_processes(&self) -> Result; - async fn get_system_info(&self) -> Result; - async fn get_process_by_pid(&self, pid: u32) -> Result, CollectionError>; -} -``` - -### DetectionService - -```rust,ignore -#[async_trait] -pub trait DetectionService: Send + Sync { - async fn execute_rules(&self, scan_context: &ScanContext) - -> Result, DetectionError>; - async fn load_rules(&self) -> Result, DetectionError>; - async fn add_rule(&self, rule: DetectionRule) -> Result<(), DetectionError>; - async fn remove_rule(&self, rule_name: &str) -> Result<(), DetectionError>; -} -``` - -### AlertSink - -```rust,ignore -#[async_trait] -pub trait AlertSink: Send + Sync { - async fn send(&self, alert: &Alert) -> Result; - async fn health_check(&self) -> HealthStatus; - fn name(&self) -> &str; -} -``` - -## Configuration API - -### Config - -```rust,ignore -pub struct Config { - app: AppConfig, - database: DatabaseConfig, - alerting: AlertingConfig, - security: SecurityConfig, -} - -impl Config { - pub async fn load_from_file(path: &str) -> Result; - pub async fn load_from_env() -> Result; - pub fn get(&self, key: &str) -> Result - where - T: DeserializeOwned; - pub fn set(&mut self, key: &str, value: T) -> Result<(), ConfigError> - where - T: Serialize; - pub fn validate(&self) -> Result<(), ConfigError>; -} -``` - -### AppConfig - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub struct AppConfig { - pub scan_interval_ms: u64, - pub batch_size: usize, - pub log_level: String, - pub data_dir: PathBuf, - pub log_dir: PathBuf, - pub pid_file: Option, - pub user: Option, - pub group: Option, - pub max_memory_mb: Option, - pub max_cpu_percent: Option, -} -``` - -## Database API - -### Database - -```rust,ignore -pub struct Database { - conn: Connection, -} - -impl Database { - pub async fn new(path: &str) -> Result; - pub async fn create_schema(&self) -> Result<(), DatabaseError>; - pub async fn insert_process(&self, process: &ProcessInfo) -> Result<(), DatabaseError>; - pub async fn get_process(&self, pid: u32) -> Result, DatabaseError>; - pub async fn query_processes( - &self, - query: &str, - params: &[&dyn ToSql], - ) -> Result, DatabaseError>; - pub async fn insert_alert(&self, alert: &Alert) -> Result<(), DatabaseError>; - pub async fn get_alerts(&self, limit: Option) -> Result, DatabaseError>; - pub async fn cleanup_old_data(&self, retention_days: u32) -> Result<(), DatabaseError>; -} -``` - -## Alerting API - -### AlertManager - -```rust,ignore -pub struct AlertManager { - sinks: Vec>, - queue: Arc>>, - max_queue_size: usize, -} - -impl AlertManager { - pub fn new() -> Self; - pub fn add_sink(&mut self, sink: Box); - pub async fn send_alert(&self, alert: Alert) -> Result<(), AlertError>; - pub async fn health_check(&self) -> HealthStatus; - pub fn queue_size(&self) -> usize; - pub fn queue_capacity(&self) -> usize; -} -``` - -### Alert Sinks - -#### SyslogSink - -```rust,ignore -pub struct SyslogSink { - facility: String, - priority: String, - tag: String, -} - -impl SyslogSink { - pub fn new(facility: &str) -> Result; - pub fn with_priority(self, priority: &str) -> Self; - pub fn with_tag(self, tag: &str) -> Self; -} -``` - -#### WebhookSink - -```rust,ignore -pub struct WebhookSink { - url: String, - method: String, - timeout: Duration, - retry_attempts: u32, - headers: HashMap, -} - -impl WebhookSink { - pub fn new(url: &str) -> Self; - pub fn with_method(self, method: &str) -> Self; - pub fn with_timeout(self, timeout: Duration) -> Self; - pub fn with_retry_attempts(self, attempts: u32) -> Self; - pub fn with_header(self, key: &str, value: &str) -> Self; -} -``` - -#### FileSink - -```rust,ignore -pub struct FileSink { - path: PathBuf, - format: OutputFormat, - rotation: RotationPolicy, - max_files: usize, -} - -impl FileSink { - pub fn new(path: &str) -> Self; - pub fn with_format(self, format: OutputFormat) -> Self; - pub fn with_rotation(self, rotation: RotationPolicy) -> Self; - pub fn with_max_files(self, max_files: usize) -> Self; -} -``` - -## CLI API - -### Cli - -```rust,ignore -pub struct Cli { - pub command: Commands, - pub config: Option, - pub log_level: String, -} - -#[derive(Subcommand)] -pub enum Commands { - Run(RunCommand), - Config(ConfigCommand), - Rules(RulesCommand), - Alerts(AlertsCommand), - Health(HealthCommand), - Query(QueryCommand), - Logs(LogsCommand), -} - -impl Cli { - pub async fn execute(self) -> Result<(), CliError>; -} -``` - -### Commands - -#### RunCommand - -```rust,ignore -#[derive(Args)] -pub struct RunCommand { - #[arg(short, long)] - pub daemon: bool, - - #[arg(short, long)] - pub foreground: bool, -} -``` - -#### ConfigCommand - -```rust,ignore -#[derive(Subcommand)] -pub enum ConfigCommand { - Show(ConfigShowCommand), - Set(ConfigSetCommand), - Get(ConfigGetCommand), - Validate(ConfigValidateCommand), - Load(ConfigLoadCommand), -} - -#[derive(Args)] -pub struct ConfigShowCommand { - #[arg(long)] - pub include_defaults: bool, - - #[arg(long)] - pub format: Option, -} -``` - -#### RulesCommand - -```rust,ignore -#[derive(Subcommand)] -pub enum RulesCommand { - List(RulesListCommand), - Add(RulesAddCommand), - Remove(RulesRemoveCommand), - Enable(RulesEnableCommand), - Disable(RulesDisableCommand), - Validate(RulesValidateCommand), - Test(RulesTestCommand), - Reload(RulesReloadCommand), -} -``` - -## IPC API - -### IpcServer - -```rust,ignore -pub struct IpcServer { - socket_path: PathBuf, - handlers: HashMap>, -} - -impl IpcServer { - pub fn new(socket_path: &str) -> Self; - pub fn add_handler(&mut self, name: &str, handler: Box); - pub async fn run(self) -> Result<(), IpcError>; -} -``` - -### IpcClient - -```rust,ignore -pub struct IpcClient { - socket_path: PathBuf, - connection: Option, -} - -impl IpcClient { - pub async fn new(socket_path: &str) -> Result; - pub async fn send_request(&self, request: IpcRequest) -> Result; - pub async fn close(self) -> Result<(), IpcError>; -} -``` - -### IPC Messages - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize)] -pub enum IpcRequest { - CollectProcesses, - GetProcess { pid: u32 }, - QueryProcesses { query: String, params: Vec }, - GetAlerts { limit: Option }, - SendAlert { alert: Alert }, - HealthCheck, -} - -#[derive(Debug, Clone, Serialize, Deserialize)] -pub enum IpcResponse { - Processes(Vec), - Process(Option), - QueryResult(Vec), - Alerts(Vec), - AlertSent, - Health(HealthStatus), - Error(String), -} -``` - -## Utility APIs - -### Logger - -```rust,ignore -pub struct Logger { - level: Level, - format: LogFormat, - output: LogOutput, -} - -impl Logger { - pub fn new() -> Self; - pub fn with_level(self, level: Level) -> Self; - pub fn with_format(self, format: LogFormat) -> Self; - pub fn with_output(self, output: LogOutput) -> Self; - pub fn init(self) -> Result<(), LogError>; -} -``` - -### Metrics - -```rust,ignore -pub struct Metrics { - registry: Registry, -} - -impl Metrics { - pub fn new() -> Self; - pub fn counter(&self, name: &str) -> Counter; - pub fn gauge(&self, name: &str) -> Gauge; - pub fn histogram(&self, name: &str) -> Histogram; - pub fn register(&self, metric: Box) -> Result<(), MetricsError>; -} -``` - -## Error Handling - -### Error Types - -All APIs use structured error types: - -```rust,ignore -#[derive(Debug, Error)] -pub enum DaemonEyeError { - #[error("Collection error: {0}")] - Collection(#[from] CollectionError), - - #[error("Database error: {0}")] - Database(#[from] DatabaseError), - - #[error("Alert error: {0}")] - Alert(#[from] AlertError), - - #[error("Configuration error: {0}")] - Config(#[from] ConfigError), - - #[error("IPC error: {0}")] - Ipc(#[from] IpcError), - - #[error("CLI error: {0}")] - Cli(#[from] CliError), -} -``` - -### Error Context - -Use `anyhow` for error context: - -```rust,ignore -use anyhow::{Context, Result}; - -pub async fn collect_processes() -> Result> { - let processes = sysinfo::System::new_all() - .processes() - .values() - .map(|p| ProcessInfo::from(p)) - .collect::>(); - - Ok(processes) -} -``` - -## Examples - -### Basic Process Monitoring - -```rust,ignore -use daemoneye_lib::alerting::AlertManager; -use daemoneye_lib::collector::ProcessCollector; -use daemoneye_lib::storage::Database; - -#[tokio::main] -async fn main() -> Result<(), Box> { - // Initialize components - let collector = ProcessCollector::new(); - let db = Database::new("processes.db").await?; - let mut alert_manager = AlertManager::new(); - - // Add alert sink - alert_manager.add_sink(Box::new(SyslogSink::new("daemon")?)); - - // Collect processes - let processes = collector.collect_processes().await?; - - // Store in database - for process in &processes { - db.insert_process(process).await?; - } - - // Check for suspicious processes - let suspicious = db - .query_processes( - "SELECT * FROM processes WHERE name LIKE '%suspicious%'", - &[], - ) - .await?; - - // Send alerts - for process in suspicious { - let alert = Alert::new("suspicious_process", process); - alert_manager.send_alert(alert).await?; - } - - Ok(()) -} -``` - -### Custom Alert Sink - -```rust,ignore -use async_trait::async_trait; -use daemoneye_lib::alerting::{Alert, AlertSink, DeliveryError, DeliveryResult}; - -pub struct CustomSink { - endpoint: String, - client: reqwest::Client, -} - -impl CustomSink { - pub fn new(endpoint: &str) -> Self { - Self { - endpoint: endpoint.to_string(), - client: reqwest::Client::new(), - } - } -} - -#[async_trait] -impl AlertSink for CustomSink { - async fn send(&self, alert: &Alert) -> Result { - let response = self - .client - .post(&self.endpoint) - .json(alert) - .send() - .await - .map_err(|e| DeliveryError::Network(e.to_string()))?; - - if response.status().is_success() { - Ok(DeliveryResult::Success) - } else { - Err(DeliveryError::Http(response.status().as_u16())) - } - } - - async fn health_check(&self) -> HealthStatus { - match self.client.get(&self.endpoint).send().await { - Ok(response) if response.status().is_success() => HealthStatus::Healthy, - _ => HealthStatus::Unhealthy, - } - } - - fn name(&self) -> &str { - "custom_sink" - } -} -``` - ---- - -*This API reference provides comprehensive documentation for all DaemonEye APIs. For additional examples and usage patterns, consult the specific API documentation.* diff --git a/docs/src/api-reference/core-api.md b/docs/src/api-reference/core-api.md deleted file mode 100644 index 80542cfe..00000000 --- a/docs/src/api-reference/core-api.md +++ /dev/null @@ -1,690 +0,0 @@ -# DaemonEye Core API Reference - -This document provides comprehensive API reference for the DaemonEye core library (`daemoneye-lib`) and its public interfaces. - -## Table of Contents - -- [Core Data Models](#core-data-models) -- [Configuration API](#configuration-api) -- [Storage API](#storage-api) -- [Detection API](#detection-api) -- [Alerting API](#alerting-api) -- [Crypto API](#crypto-api) -- [Telemetry API](#telemetry-api) -- [Error Types](#error-types) - -## Core Data Models - -### ProcessRecord - -Represents a single process snapshot with comprehensive metadata. - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub struct ProcessRecord { - /// Unique identifier for this process record - pub id: Uuid, - - /// Scan identifier this record belongs to - pub scan_id: i64, - - /// Collection timestamp in milliseconds since Unix epoch - pub collection_time: i64, - - /// Process ID - pub pid: u32, - - /// Parent process ID - pub ppid: Option, - - /// Process name - pub name: String, - - /// Path to executable file - pub executable_path: Option, - - /// Command line arguments - pub command_line: Vec, - - /// Process start time in milliseconds since Unix epoch - pub start_time: Option, - - /// CPU usage percentage - pub cpu_usage: Option, - - /// Memory usage in bytes - pub memory_usage: Option, - - /// SHA-256 hash of executable file - pub executable_hash: Option, - - /// Hash algorithm used (always "sha256") - pub hash_algorithm: Option, - - /// User ID running the process - pub user_id: Option, - - /// Whether process data was accessible - pub accessible: bool, - - /// Whether executable file exists - pub file_exists: bool, - - /// Platform-specific data - pub platform_data: Option, -} -``` - -**Example Usage**: - -```rust,ignore -use daemoneye_lib::models::ProcessRecord; -use uuid::Uuid; - -fn create_process_record() -> ProcessRecord { - ProcessRecord { - id: Uuid::new_v4(), - scan_id: 12345, - collection_time: 1640995200000, // 2022-01-01 00:00:00 UTC - pid: 1234, - ppid: Some(1), - name: "chrome".to_string(), - executable_path: Some("/usr/bin/chrome".into()), - command_line: vec!["chrome".to_string(), "--no-sandbox".to_string()], - start_time: Some(1640995100000), - cpu_usage: Some(15.5), - memory_usage: Some(1073741824), // 1GB - executable_hash: Some("a1b2c3d4e5f6...".to_string()), - hash_algorithm: Some("sha256".to_string()), - user_id: Some("1000".to_string()), - accessible: true, - file_exists: true, - platform_data: Some(serde_json::json!({ - "thread_count": 25, - "priority": "normal" - })), - } -} - -// Usage example -let record = create_process_record(); -println!("Process {} (PID: {}) is using {:.1}% CPU", - record.name, record.pid, record.cpu_usage.unwrap_or(0.0)); -``` - -### Alert - -Represents a detection result with full context and metadata. - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub struct Alert { - /// Unique alert identifier - pub id: Uuid, - - /// Alert timestamp in milliseconds since Unix epoch - pub alert_time: i64, - - /// Rule identifier that generated this alert - pub rule_id: String, - - /// Alert title - pub title: String, - - /// Alert description - pub description: String, - - /// Alert severity level - pub severity: AlertSeverity, - - /// Scan identifier (if applicable) - pub scan_id: Option, - - /// Affected process IDs - pub affected_processes: Vec, - - /// Number of affected processes - pub process_count: i32, - - /// Additional alert data as JSON - pub alert_data: serde_json::Value, - - /// Rule execution time in milliseconds - pub rule_execution_time_ms: Option, - - /// Deduplication key - pub dedupe_key: String, -} - -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub enum AlertSeverity { - Low, - Medium, - High, - Critical, -} -``` - -**Example Usage**: - -```rust,ignore -use daemoneye_lib::models::{Alert, AlertSeverity}; -use uuid::Uuid; - -let alert = Alert { - id: Uuid::new_v4(), - alert_time: 1640995200000, - rule_id: "suspicious-processes".to_string(), - title: "Suspicious Process Detected".to_string(), - description: "Process with suspicious name detected".to_string(), - severity: AlertSeverity::High, - scan_id: Some(12345), - affected_processes: vec![1234, 5678], - process_count: 2, - alert_data: serde_json::json!({ - "processes": [ - {"pid": 1234, "name": "malware.exe"}, - {"pid": 5678, "name": "backdoor.exe"} - ] - }), - rule_execution_time_ms: Some(15), - dedupe_key: "suspicious-processes:malware.exe".to_string(), -}; -``` - -### DetectionRule - -Represents a SQL-based detection rule with metadata and versioning. - -```rust,ignore -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub struct DetectionRule { - /// Unique rule identifier - pub id: String, - - /// Rule name - pub name: String, - - /// Rule description - pub description: Option, - - /// Rule version - pub version: i32, - - /// SQL query for detection - pub sql_query: String, - - /// Whether rule is enabled - pub enabled: bool, - - /// Alert severity for this rule - pub severity: AlertSeverity, - - /// Rule category - pub category: Option, - - /// Rule tags - pub tags: Vec, - - /// Rule author - pub author: Option, - - /// Creation timestamp - pub created_at: i64, - - /// Last update timestamp - pub updated_at: i64, - - /// Rule source type - pub source_type: RuleSourceType, - - /// Source file path (if applicable) - pub source_path: Option, -} - -#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] -pub enum RuleSourceType { - Builtin, - File, - User, -} -``` - -## Configuration API - -### Hierarchical Configuration - -The configuration system supports hierarchical loading with environment variable substitution. - -```rust,ignore -use daemoneye_lib::config::{Config, ConfigBuilder, ConfigError}; - -// Create configuration builder -let mut builder = ConfigBuilder::new(); - -// Load configuration from multiple sources -builder - .add_embedded_defaults()? - .add_file("/etc/daemoneye/config.yaml")? - .add_file("~/.config/daemoneye/config.yaml")? - .add_environment("DaemonEye_")? - .add_cli_args(args)?; - -// Build final configuration -let config: Config = builder.build()?; - -// Access configuration values -let scan_interval = config.get::("app.scan_interval_ms")?; -let log_level = config.get::("app.log_level")?; -``` - -### Configuration Validation - -```rust,ignore -use daemoneye_lib::config::{ConfigValidator, ValidationResult}; - -let validator = ConfigValidator::new(); -let result: ValidationResult = validator.validate(&config)?; - -if !result.is_valid() { - for error in result.errors() { - eprintln!("Configuration error: {}", error); - } -} -``` - -### Environment Variable Substitution - -```rust,ignore -use daemoneye_lib::config::EnvironmentSubstitutor; - -let substitutor = EnvironmentSubstitutor::new(); -let config_with_env = substitutor.substitute(config)?; -``` - -## Storage API - -### Event Store (redb) - -High-performance embedded database for process data storage. - -```rust,ignore -use daemoneye_lib::storage::{EventStore, EventStoreConfig, ProcessQuery}; - -// Create event store -let config = EventStoreConfig { - path: "/var/lib/daemoneye/events.redb".into(), - max_size_mb: 10240, - wal_mode: true, - max_connections: 10, -}; - -let event_store = EventStore::new(config)?; - -// Store process records -let processes = vec![process_record1, process_record2]; -event_store.store_processes(&processes).await?; - -// Query processes -let query = ProcessQuery::new() - .with_pid(1234) - .with_name("chrome") - .with_time_range(start_time, end_time); - -let results = event_store.query_processes(&query).await?; - -// Export data -let export_config = ExportConfig { - format: ExportFormat::Json, - output_path: "/tmp/export.json".into(), - time_range: Some((start_time, end_time)), -}; - -event_store.export_data(&export_config).await?; -``` - -### Audit Ledger (SQLite) - -Tamper-evident audit trail with cryptographic integrity. - -```rust,ignore -use daemoneye_lib::storage::{AuditLedger, AuditEntry, AuditRecord}; - -// Create audit ledger -let audit_ledger = AuditLedger::new("/var/lib/daemoneye/audit.sqlite")?; - -// Log audit entry -let entry = AuditEntry { - actor: "procmond".to_string(), - action: "process_collection".to_string(), - payload: serde_json::json!({ - "process_count": 150, - "scan_id": 12345 - }), -}; - -let record = audit_ledger.append_entry(&entry).await?; - -// Verify audit chain -let verification_result = audit_ledger.verify_chain().await?; -if !verification_result.is_valid() { - eprintln!("Audit chain verification failed: {:?}", verification_result.errors()); -} -``` - -## Detection API - -### SQL Validator - -Comprehensive SQL validation to prevent injection attacks. - -```rust,ignore -use daemoneye_lib::detection::{SqlValidator, ValidationResult, ValidationError}; - -// Create SQL validator -let validator = SqlValidator::new() - .with_allowed_functions(vec![ - "count", "sum", "avg", "min", "max", - "length", "substr", "upper", "lower", - "datetime", "strftime" - ]) - .with_read_only_mode(true) - .with_timeout(Duration::from_secs(30)); - -// Validate SQL query -let sql = "SELECT pid, name, cpu_usage FROM processes WHERE cpu_usage > 50.0"; -let result: ValidationResult = validator.validate_query(sql)?; - -match result { - ValidationResult::Valid => println!("Query is valid"), - ValidationResult::Invalid(errors) => { - for error in errors { - eprintln!("Validation error: {}", error); - } - } -} -``` - -### Detection Engine - -SQL-based detection rule execution with security validation. - -```rust,ignore -use daemoneye_lib::detection::{DetectionEngine, DetectionResult, RuleExecutionConfig}; - -// Create detection engine -let config = DetectionEngineConfig { - event_store: event_store.clone(), - rule_timeout: Duration::from_secs(30), - max_concurrent_rules: 10, - enable_metrics: true, -}; - -let detection_engine = DetectionEngine::new(config)?; - -// Execute detection rules -let execution_config = RuleExecutionConfig { - scan_id: Some(12345), - rule_ids: None, // Execute all enabled rules - timeout: Duration::from_secs(60), -}; - -let results: Vec = detection_engine - .execute_rules(&execution_config) - .await?; - -// Process detection results -for result in results { - if !result.alerts.is_empty() { - println!("Rule {} generated {} alerts", result.rule_id, result.alerts.len()); - } -} -``` - -### Rule Manager - -Detection rule management with hot-reloading support. - -```rust,ignore -use daemoneye_lib::detection::{RuleManager, RuleManagerConfig}; - -// Create rule manager -let config = RuleManagerConfig { - rules_path: "/etc/daemoneye/rules".into(), - enable_hot_reload: true, - validation_enabled: true, -}; - -let rule_manager = RuleManager::new(config)?; - -// Load rules -let rules = rule_manager.load_rules().await?; - -// Enable/disable rules -rule_manager.enable_rule("suspicious-processes").await?; -rule_manager.disable_rule("test-rule").await?; - -// Validate rule -let validation_result = rule_manager.validate_rule_file("/path/to/rule.sql").await?; - -// Test rule -let test_result = rule_manager.test_rule("suspicious-processes", test_data).await?; -``` - -## Alerting API - -### Alert Manager - -Alert generation, deduplication, and delivery management. - -```rust,ignore -use daemoneye_lib::alerting::{AlertManager, AlertManagerConfig, DeduplicationConfig}; - -// Create alert manager -let config = AlertManagerConfig { - deduplication: DeduplicationConfig { - enabled: true, - window_minutes: 60, - key_fields: vec!["rule_id".to_string(), "process_name".to_string()], - }, - max_queue_size: 10000, - delivery_timeout: Duration::from_secs(30), -}; - -let alert_manager = AlertManager::new(config)?; - -// Generate alert -let alert = alert_manager.generate_alert( - &detection_result, - &process_data -).await?; - -// Deliver alert -if let Some(alert) = alert { - let delivery_result = alert_manager.deliver_alert(&alert).await?; - println!("Alert delivered: {:?}", delivery_result); -} -``` - -### Alert Sinks - -Pluggable alert delivery channels. - -```rust,ignore -use daemoneye_lib::alerting::sinks::{AlertSink, StdoutSink, SyslogSink, WebhookSink}; - -// Create alert sinks -let stdout_sink = StdoutSink::new(OutputFormat::Json); -let syslog_sink = SyslogSink::new(SyslogConfig { - facility: SyslogFacility::Daemon, - tag: "daemoneye".to_string(), - host: "localhost".to_string(), - port: 514, -}); - -let webhook_sink = WebhookSink::new(WebhookConfig { - url: "https://your-siem.com/webhook".parse()?, - headers: vec![ - ("Authorization".to_string(), "Bearer token".to_string()), - ], - timeout: Duration::from_secs(30), - retry_attempts: 3, -}); - -// Send alert to all sinks -let sinks: Vec> = vec![ - Box::new(stdout_sink), - Box::new(syslog_sink), - Box::new(webhook_sink), -]; - -for sink in sinks { - let result = sink.send(&alert).await?; - println!("Sink {} result: {:?}", sink.name(), result); -} -``` - -## Crypto API - -### Hash Chain - -Cryptographic hash chain for audit trail integrity. - -```rust,ignore -use daemoneye_lib::crypto::{HashChain, HashChainConfig, ChainVerificationResult}; - -// Create hash chain -let config = HashChainConfig { - algorithm: HashAlgorithm::Blake3, - enable_signatures: true, - private_key_path: Some("/etc/daemoneye/private.key".into()), -}; - -let mut hash_chain = HashChain::new(config)?; - -// Append entry to chain -let entry = AuditEntry { - actor: "procmond".to_string(), - action: "process_collection".to_string(), - payload: serde_json::json!({"process_count": 150}), -}; - -let record = hash_chain.append_entry(&entry).await?; -println!("Chain entry: {}", record.entry_hash); - -// Verify chain integrity -let verification_result: ChainVerificationResult = hash_chain.verify_chain().await?; -if verification_result.is_valid() { - println!("Chain verification successful"); -} else { - eprintln!("Chain verification failed: {:?}", verification_result.errors()); -} -``` - -### Digital Signatures - -Ed25519 digital signatures for enhanced integrity. - -```rust,ignore -use daemoneye_lib::crypto::{SignatureManager, SignatureConfig}; - -// Create signature manager -let config = SignatureConfig { - private_key_path: "/etc/daemoneye/private.key".into(), - public_key_path: "/etc/daemoneye/public.key".into(), -}; - -let signature_manager = SignatureManager::new(config)?; - -// Sign data -let data = b"important audit data"; -let signature = signature_manager.sign(data)?; - -// Verify signature -let is_valid = signature_manager.verify(data, &signature)?; -println!("Signature valid: {}", is_valid); -``` - -## Telemetry API - -### Metrics Collection - -Prometheus-compatible metrics collection. - -```rust,ignore -use daemoneye_lib::telemetry::{MetricsCollector, MetricType, MetricValue}; - -// Create metrics collector -let metrics_collector = MetricsCollector::new()?; - -// Record metrics -metrics_collector.record_counter("processes_collected_total", 150)?; -metrics_collector.record_gauge("active_processes", 45.0)?; -metrics_collector.record_histogram("collection_duration_seconds", 2.5)?; - -// Export metrics -let metrics_data = metrics_collector.export_metrics()?; -println!("Metrics: {}", metrics_data); -``` - -### Health Monitoring - -System health monitoring and status reporting. - -```rust,ignore -use daemoneye_lib::telemetry::{HealthMonitor, HealthStatus, ComponentHealth}; - -// Create health monitor -let health_monitor = HealthMonitor::new()?; - -// Check system health -let health_status: HealthStatus = health_monitor.check_system_health().await?; - -println!("System Health: {:?}", health_status.status); -for (component, health) in health_status.components { - println!("{}: {:?}", component, health); -} - -// Check specific component -let db_health: ComponentHealth = health_monitor.check_component("database").await?; -println!("Database Health: {:?}", db_health); -``` - -## Error Types - -### Core Error Types - -```rust,ignore -use daemoneye_lib::errors::{DaemonEyeError, DaemonEyeErrorKind}; - -// Error handling example -match some_operation().await { - Ok(result) => println!("Success: {:?}", result), - Err(DaemonEyeError::Configuration(e)) => { - eprintln!("Configuration error: {}", e); - } - Err(DaemonEyeError::Database(e)) => { - eprintln!("Database error: {}", e); - } - Err(DaemonEyeError::Detection(e)) => { - eprintln!("Detection error: {}", e); - } - Err(e) => { - eprintln!("Unexpected error: {}", e); - } -} -``` - -### Error Categories - -- **ConfigurationError**: Configuration loading and validation errors -- **DatabaseError**: Database operation errors -- **DetectionError**: Detection rule execution errors -- **AlertingError**: Alert generation and delivery errors -- **CryptoError**: Cryptographic operation errors -- **ValidationError**: Data validation errors -- **IoError**: I/O operation errors - ---- - -*This API reference provides comprehensive documentation for the DaemonEye core library. For additional examples and advanced usage, consult the source code and integration tests.* diff --git a/docs/src/cli-reference.md b/docs/src/cli-reference.md deleted file mode 100644 index 8727b002..00000000 --- a/docs/src/cli-reference.md +++ /dev/null @@ -1,406 +0,0 @@ -# CLI Reference - -This document provides comprehensive reference information for all DaemonEye command-line interfaces. - ---- - -## Table of Contents - -[TOC] - ---- - -## Overview - -DaemonEye provides three main command-line tools: - -- **procmond**: Privileged process collector daemon -- **daemoneye-agent**: Detection orchestrator and lifecycle manager -- **daemoneye-cli**: Command-line interface for queries and management - -## procmond - -The privileged process monitoring daemon that collects process information with minimal attack surface. - -### Usage - -```bash -procmond [OPTIONS] -``` - -### Options - -| Option | Short | Default | Description | -| --------------------- | ----- | --------------------------------- | ------------------------------------------- | -| `--database` | `-d` | `/var/lib/daemoneye/processes.db` | Database path for storing process data | -| `--log-level` | `-l` | `info` | Log level (debug, info, warn, error) | -| `--interval` | `-i` | `30` | Collection interval in seconds (5-3600) | -| `--max-processes` | | `0` | Maximum processes per cycle (0 = unlimited) | -| `--enhanced-metadata` | | | Enable enhanced metadata collection | -| `--compute-hashes` | | | Enable executable hashing for integrity | -| `--help` | `-h` | | Print help information | -| `--version` | `-V` | | Print version information | - -### Examples - -```bash -# Basic process monitoring with 30-second intervals -procmond --database /var/lib/daemoneye/processes.db --interval 30 - -# Enhanced collection with metadata and hashing -procmond --enhanced-metadata --compute-hashes --interval 60 - -# Debug mode with verbose logging -procmond --log-level debug --interval 10 - -# Limited collection for testing -procmond --max-processes 100 --interval 5 -``` - -### Configuration - -`procmond` is orchestrated by `daemoneye-agent`; collectors do not consume component-specific configuration files. When the binary is launched directly (for example during development or troubleshooting) it honours the following sources: - -1. Command-line flags (highest precedence) -2. Environment variables (`PROCMOND_*`) typically injected by the agent -3. System DaemonEye configuration file (`/etc/daemoneye/config.toml`) -4. Embedded defaults (lowest precedence) - -Per-user configuration is not supported for collectors; only the operator-facing CLI honours user-scoped overrides when invoked directly. - -Operators should configure collection behaviour through the agent, which materialises these settings when spawning the collector. - -### Exit Codes - -| Code | Description | -| ---- | ---------------------------------------------------------------------------------------- | -| 0 | Success | -| 1 | Unhandled error returned from the runtime (includes configuration, permission, database) | -| 2 | CLI argument parsing failure reported by `clap` | - -## daemoneye-agent - -The detection orchestrator that manages procmond lifecycle, executes detection rules, and handles alerting. - -### Usage - -```bash -daemoneye-agent [OPTIONS] -``` - -### Options - -| Option | Short | Default | Description | -| ------------- | ----- | --------------------------------- | ------------------------------------ | -| `--database` | `-d` | `/var/lib/daemoneye/processes.db` | Database path for process data | -| `--log-level` | `-l` | `info` | Log level (debug, info, warn, error) | -| `--help` | `-h` | | Print help information | -| `--version` | `-V` | | Print version information | - -### Examples - -```bash -# Start orchestrator with default settings -daemoneye-agent - -# Use custom database location -daemoneye-agent --database /custom/path/processes.db - -# Enable debug logging -daemoneye-agent --log-level debug - -# Test mode (exits immediately for integration tests) -DAEMONEYE_AGENT_TEST_MODE=1 daemoneye-agent -``` - -### Environment Variables - -| Variable | Description | -| --------------------------- | ----------------------------------------------- | -| `DAEMONEYE_AGENT_TEST_MODE` | Set to `1` to enable test mode (immediate exit) | - -### Features - -- **Embedded EventBus Broker**: Runs daemoneye-eventbus broker for multi-collector coordination -- **IPC Server**: Provides IPC server for CLI communication via protobuf over Unix sockets/named pipes -- **IPC Client**: Communicates with procmond via protobuf over Unix sockets/named pipes -- **Detection Engine**: Executes SQL-based detection rules against collected data -- **Alert Management**: Multi-channel alert delivery (stdout, syslog, webhooks, email) -- **Graceful Shutdown**: Handles SIGTERM/SIGINT for clean shutdown - -### Configuration - -daemoneye-agent supports hierarchical configuration loading: - -1. Command-line flags (highest precedence) -2. Environment variables (`DAEMONEYE_AGENT_*`) -3. User configuration file (`~/.config/daemoneye-agent/config.yaml`) -4. System configuration file (`/etc/daemoneye-agent/config.yaml`) -5. Embedded defaults (lowest precedence) - -## daemoneye-cli - -The command-line interface for querying database statistics, health checks, and system management. - -### Usage - -```bash -daemoneye-cli [OPTIONS] -``` - -### Options - -| Option | Short | Default | Description | -| ------------ | ----- | --------------------------------- | --------------------------- | -| `--database` | `-d` | `/var/lib/daemoneye/processes.db` | Database path for queries | -| `--format` | `-f` | `human` | Output format (human, json) | -| `--help` | `-h` | | Print help information | -| `--version` | `-V` | | Print version information | - -### Examples - -```bash -# View database statistics in human-readable format -daemoneye-cli --database /var/lib/daemoneye/processes.db --format human - -# Get statistics in JSON format for scripting -daemoneye-cli --database /var/lib/daemoneye/processes.db --format json - -# Use default database location -daemoneye-cli --format json -``` - -### Output Formats - -#### Human Format - -```text -DaemonEye Database Statistics -============================ -Processes: 1234 -Rules: 5 -Alerts: 42 -System Info: 1 -Scans: 100 -Health status: Healthy -``` - -#### JSON Format - -```json -{ - "processes": 1234, - "rules": 5, - "alerts": 42, - "system_info": 1, - "scans": 100, - "health_status": "Healthy" -} -``` - -### Configuration - -daemoneye-cli supports hierarchical configuration loading: - -1. Command-line flags (highest precedence) -2. Environment variables (`DAEMONEYE_CLI_*`) -3. User configuration file (`~/.config/daemoneye-cli/config.yaml`) -4. System configuration file (`/etc/daemoneye-cli/config.yaml`) -5. Embedded defaults (lowest precedence) - -## Common Patterns - -### Basic Monitoring Setup - -```bash -# Terminal 1: Start the orchestrator -daemoneye-agent --log-level info - -# Terminal 2: Monitor database statistics -watch -n 5 'daemoneye-cli --format json' - -# Terminal 3: Run procmond directly (optional) -procmond --enhanced-metadata --compute-hashes -``` - -### Testing and Development - -```bash -# Test procmond collection -procmond --interval 5 --max-processes 10 --log-level debug - -# Test agent in test mode -DAEMONEYE_AGENT_TEST_MODE=1 daemoneye-agent - -# Check database growth -daemoneye-cli --format json | jq '.processes' -``` - -### Production Deployment - -```bash -# Start agent as service -systemctl start daemoneye-agent - -# Monitor health -daemoneye-cli --format json | jq '.processes, .alerts' - -# Check logs -journalctl -u daemoneye-agent -f -``` - -## Shell Completions - -All DaemonEye CLI tools support shell completions for bash, zsh, fish, and PowerShell. - -### Generate Completions - -```bash -# Bash -daemoneye-cli --generate-completion bash > /etc/bash_completion.d/daemoneye-cli - -# Zsh -daemoneye-cli --generate-completion zsh > ~/.zsh/completions/_daemoneye-cli - -# Fish -daemoneye-cli --generate-completion fish > ~/.config/fish/completions/daemoneye-cli.fish - -# PowerShell -daemoneye-cli --generate-completion powershell > DaemonEye.ps1 -``` - -## Error Handling - -All CLI tools follow consistent error handling patterns: - -- **Exit Code 0**: Success -- **Exit Code 1**: General error -- **Exit Code 2**: CLI argument parsing failure -- **Exit Code 3**: Permission denied -- **Exit Code 4**: Database error - -### Common Error Messages - -| Error | Cause | Solution | -| --------------------- | ------------------------------------- | --------------------------------------------------------- | -| `Permission denied` | Insufficient privileges | Run with appropriate privileges or check file permissions | -| `Database locked` | Another process is using the database | Stop other DaemonEye processes or check for stale locks | -| `Invalid interval` | Interval outside 5-3600 range | Use interval between 5 and 3600 seconds | -| `Configuration error` | Invalid configuration file | Check configuration syntax and values | - -## Environment Variables - -### Global Environment Variables - -| Variable | Description | Default | -| ---------------- | --------------------------------------- | -------------- | -| `NO_COLOR` | Disable colored output | Not set | -| `TERM` | Terminal type (affects color detection) | System default | -| `RUST_LOG` | Rust logging configuration | Not set | -| `RUST_BACKTRACE` | Enable Rust backtraces | Not set | - -### Component-Specific Variables - -#### procmond - -| Variable | Description | Default | -| -------------------- | ------------------- | --------------------------------- | -| `PROCMOND_DATABASE` | Database path | `/var/lib/daemoneye/processes.db` | -| `PROCMOND_LOG_LEVEL` | Log level | `info` | -| `PROCMOND_INTERVAL` | Collection interval | `30` | - -#### daemoneye-agent - -| Variable | Description | Default | -| --------------------------- | ---------------- | --------------------------------- | -| `DAEMONEYE_AGENT_DATABASE` | Database path | `/var/lib/daemoneye/processes.db` | -| `DAEMONEYE_AGENT_LOG_LEVEL` | Log level | `info` | -| `DAEMONEYE_AGENT_TEST_MODE` | Enable test mode | Not set | - -#### daemoneye-cli - -| Variable | Description | Default | -| ------------------------ | ------------- | --------------------------------- | -| `DAEMONEYE_CLI_DATABASE` | Database path | `/var/lib/daemoneye/processes.db` | -| `DAEMONEYE_CLI_FORMAT` | Output format | `human` | - -## Integration Examples - -### Systemd Service - -```ini -[Unit] -Description=DaemonEye Agent -After=network.target - -[Service] -Type=simple -User=daemoneye -Group=daemoneye -ExecStart=/usr/local/bin/daemoneye-agent --database /var/lib/daemoneye/processes.db -Restart=always -RestartSec=5 - -[Install] -WantedBy=multi-user.target -``` - -### Docker Deployment - -```dockerfile -FROM rust:1.91-slim as builder -COPY . /app -WORKDIR /app -RUN cargo build --release - -FROM debian:bookworm-slim -RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/* -COPY --from=builder /app/target/release/daemoneye-agent /usr/local/bin/ -COPY --from=builder /app/target/release/daemoneye-cli /usr/local/bin/ -COPY --from=builder /app/target/release/procmond /usr/local/bin/ - -VOLUME ["/data"] - -CMD ["daemoneye-agent", "--database", "/data/processes.db"] -``` - -### Kubernetes DaemonSet - -```yaml -apiVersion: apps/v1 -kind: DaemonSet -metadata: - name: daemoneye -spec: - selector: - matchLabels: - app: daemoneye - template: - metadata: - labels: - app: daemoneye - spec: - hostPID: true - containers: - - name: daemoneye-agent - image: daemoneye/daemoneye:latest - securityContext: - privileged: true - volumeMounts: - - name: data - mountPath: /data - - name: proc - mountPath: /host/proc - readOnly: true - volumes: - - name: data - hostPath: - path: /var/lib/daemoneye - - name: proc - hostPath: - path: /proc -``` - ---- - -*This CLI reference provides comprehensive information for using DaemonEye command-line tools. For additional help, use the `--help` flag with any command or consult the user guides.* diff --git a/docs/src/deployment.md b/docs/src/deployment.md deleted file mode 100644 index 06739068..00000000 --- a/docs/src/deployment.md +++ /dev/null @@ -1,579 +0,0 @@ -# Deployment Documentation - -This section contains comprehensive deployment guides for DaemonEye, covering installation, configuration, and deployment strategies across different platforms and environments. - ---- - -## Table of Contents - -[TOC] - ---- - -## Installation Guide - -Complete installation instructions for all supported platforms including Linux, macOS, and Windows. - -[Read Installation Guide →](./deployment/installation.md) - -## Configuration Guide - -Comprehensive configuration management covering all aspects of DaemonEye setup, tuning, and customization. - -[Read Configuration Guide →](./deployment/configuration.md) - -## Docker Deployment - -Complete guide for containerizing and deploying DaemonEye using Docker and Docker Compose. - -[Read Docker Guide →](./deployment/docker.md) - -## Deployment Overview - -### Supported Platforms - -DaemonEye supports deployment on: - -- **Linux**: Ubuntu, RHEL, CentOS, Debian, Arch Linux -- **macOS**: 10.14+ (Mojave or later) -- **Windows**: Windows 10+ or Windows Server 2016+ -- **Containers**: Docker, Podman, containerd - -> [!NOTE] -> **Container Runtime Notes:** -> -> - **Docker**: Most common, requires privileged containers for host process monitoring -> - **Podman**: Rootless containers supported, better security isolation -> - ⚠️ **eBPF Limitation**: Rootless containers may have limited eBPF functionality due to kernel capabilities restrictions -> - **containerd**: Lower-level runtime, requires additional configuration for privileged access - -### Deployment Methods - -1. **Package Managers**: APT, YUM, Homebrew, Chocolatey -2. **Pre-built Binaries**: Direct download and installation -3. **Source Build**: Compile from source code -4. **Release Tooling**: GoReleaser for automated cross-platform builds -5. **Containers**: Docker images and container deployment -6. **Cloud**: AWS, Azure, GCP marketplace deployments - -> [!CAUTION] -> **Orchestration platforms (Kubernetes, Docker Swarm, Nomad) are not officially supported.** While technically possible to deploy DaemonEye on these platforms, they are not recommended for production use due to: -> -> - Lack of native DaemonSet support (except Kubernetes) -> - Complex privileged container requirements -> - Node-specific monitoring constraints -> - Limited testing and validation - -### Architecture Considerations - -#### Single Node Deployment - -For small to medium environments: - -```mermaid -graph TB - subgraph "Single Node" - A[ProcMonD] - B[daemoneye-agent] - C[CLI] - D[Database] - - A <--> B - B <--> C - B <--> D - end -``` - -#### Multi-Node Deployment - -Each host runs the same single-node topology independently. Fleet-wide aggregation across nodes is handled by commercial tiers and is outside the scope of this repo. - -#### Container Deployment - -For containerized environments, ProcMonD can be deployed in two ways: - -> [!WARNING] -> Containerized ProcMonD only works on Linux hosts. macOS and Windows must use host process deployment. - -```mermaid -graph TB - subgraph "Container Host" - A2[ProcMonD
Host Process] - - subgraph "Containers" - A1[ProcMonD
Container
privileged] - B[daemoneye-agent
Container] - C[CLI] - end - - A1 <-->|Option 1| B - A2 <-->|Option 2| B - B <--> C - end -``` - -**Deployment Recommendations:** - -- **Option 1 (Containerized ProcMonD)**: Recommended for containerized environments where you want full containerization. Requires privileged container access to monitor host processes. -- **Option 2 (Host Process ProcMonD)**: Recommended for hybrid deployments where you want to minimize container privileges while maintaining containerized management components. - -> [!WARNING] -> Option 1 requires running a privileged container, which grants the container access to the host system. This increases the attack surface and should only be used in trusted environments with proper security controls in place. - -## Quick Start - -### Docker Quick Start - -```bash -# Pull the latest image -docker pull daemoneye/daemoneye:latest - -# Run with basic configuration -docker run -d --name daemoneye \ - --privileged \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - daemoneye/daemoneye:latest - -# Check status -docker logs daemoneye -``` - -### Package Manager Quick Start - -**Ubuntu/Debian**: - -```bash -# Add repository -wget -qO - https://packages.daemoneye.com/apt/key.gpg | sudo apt-key add - -echo "deb https://packages.daemoneye.com/apt stable main" | sudo tee /etc/apt/sources.list.d/daemoneye.list - -# Install -sudo apt update -sudo apt install daemoneye - -# Start service -sudo systemctl start daemoneye -sudo systemctl enable daemoneye -``` - -**RHEL/CentOS**: - -```bash -# Add repository -sudo tee /etc/yum.repos.d/daemoneye.repo << 'EOF' -[daemoneye] -name=DaemonEye -baseurl=https://packages.daemoneye.com/yum/stable/ -enabled=1 -gpgcheck=1 -gpgkey=https://packages.daemoneye.com/apt/key.gpg -EOF - -# Install -sudo yum install daemoneye - -# Start service -sudo systemctl start daemoneye -sudo systemctl enable daemoneye -``` - -**macOS**: - -```bash -# Install with Homebrew -brew tap daemoneye/daemoneye -brew install daemoneye - -# Start service -brew services start daemoneye -``` - -**Windows**: - -```powershell -# Install with Chocolatey -choco install daemoneye - -# Start service -Start-Service DaemonEye -``` - -## Configuration Management - -### Environment Variables - -DaemonEye supports configuration through environment variables: - -```bash -# Basic configuration -export DaemonEye_LOG_LEVEL=info -export DaemonEye_SCAN_INTERVAL_MS=30000 -export DaemonEye_BATCH_SIZE=1000 - -# Database configuration -export DaemonEye_DATABASE_PATH=/var/lib/daemoneye/processes.db -export DaemonEye_DATABASE_RETENTION_DAYS=30 - -# Alerting configuration -export DaemonEye_ALERTING_ENABLED=true -export DaemonEye_ALERTING_SINKS_0_TYPE=syslog -export DaemonEye_ALERTING_SINKS_0_FACILITY=daemon -``` - -### Configuration Files - -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) - -### Basic Configuration - -```yaml -# /etc/daemoneye/config.yaml -app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - data_dir: /var/lib/daemoneye - log_dir: /var/log/daemoneye - -database: - path: /var/lib/daemoneye/processes.db - retention_days: 30 - max_connections: 10 - -alerting: - enabled: true - sinks: - - type: syslog - enabled: true - facility: daemon - priority: info - - type: webhook - enabled: false - url: https://alerts.example.com/webhook - timeout_ms: 5000 - retry_attempts: 3 - -security: - enable_privilege_dropping: true - drop_to_user: daemoneye - drop_to_group: daemoneye - enable_audit_logging: true -``` - -## Production Deployment - -### Resource Requirements - -**Minimum Requirements**: - -- CPU: 1 core -- RAM: 512MB -- Storage: 1GB -- Network: 100Mbps - -**Recommended Requirements**: - -- CPU: 2+ cores -- RAM: 2GB+ -- Storage: 10GB+ -- Network: 1Gbps - -**High-Performance Requirements**: - -- CPU: 4+ cores -- RAM: 8GB+ -- Storage: 100GB+ -- Network: 10Gbps - -### Security Considerations - -1. **Principle of Least Privilege**: Run with minimal required privileges -2. **Network Security**: Use TLS for all network communications -3. **Data Protection**: Encrypt sensitive data at rest and in transit -4. **Access Control**: Implement proper authentication and authorization -5. **Audit Logging**: Enable comprehensive audit logging - -### Performance Tuning - -**CPU Optimization**: - -```yaml -app: - scan_interval_ms: 60000 # Reduce scan frequency - batch_size: 500 # Smaller batches - max_cpu_percent: 5.0 # Limit CPU usage -``` - -**Memory Optimization**: - -```yaml -app: - max_memory_mb: 512 # Limit memory usage - batch_size: 250 # Smaller batches - gc_interval_ms: 300000 # Garbage collection interval -``` - -**Database Optimization**: - -```yaml -database: - cache_size: -128000 # 128MB cache - temp_store: MEMORY # Use memory for temp tables - synchronous: NORMAL # Balance safety and performance - wal_mode: true # Enable WAL mode -``` - -### Monitoring and Observability - -**Metrics Collection**: - -```yaml -observability: - enable_metrics: true - metrics_port: 9090 - metrics_path: /metrics -``` - -**Health Checks**: - -```yaml -observability: - enable_health_checks: true - health_check_port: 8080 - health_check_path: /health -``` - -**Logging**: - -```yaml -observability: - logging: - enable_structured_logging: true - log_format: json - enable_log_rotation: true - max_log_file_size_mb: 100 - max_log_files: 10 -``` - -## Container Deployment - -### Docker Compose - -```yaml -version: '3.8' - -services: - procmond: - image: daemoneye/procmond:latest - container_name: daemoneye-procmond - privileged: true - volumes: - - /var/lib/daemoneye:/data - - /var/log/daemoneye:/logs - - ./config:/config:ro - environment: - - DaemonEye_LOG_LEVEL=info - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - command: [--config, /config/config.yaml] - restart: unless-stopped - - daemoneye-agent: - image: daemoneye/daemoneye-agent:latest - container_name: daemoneye-agent - depends_on: - - procmond - volumes: - - /var/lib/daemoneye:/data - - /var/log/daemoneye:/logs - - ./config:/config:ro - environment: - - DaemonEye_LOG_LEVEL=info - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - command: [--config, /config/config.yaml] - restart: unless-stopped - - daemoneye-cli: - image: daemoneye/daemoneye-cli:latest - container_name: daemoneye-cli - depends_on: - - daemoneye-agent - volumes: - - /var/lib/daemoneye:/data - - ./config:/config:ro - environment: - - DaemonEye_DATA_DIR=/data - command: [--help] - restart: no -``` - -## Cloud Deployment - -### AWS Deployment - -**EC2 Instance**: - -```bash -# Launch EC2 instance -aws ec2 run-instances \ - --image-id ami-0c02fb55956c7d316 \ - --instance-type t3.medium \ - --key-name your-key \ - --security-group-ids sg-12345678 \ - --subnet-id subnet-12345678 \ - --user-data file://user-data.sh -``` - -### Azure Deployment - -**Azure Container Instances**: - -```bash -# Deploy container -az container create \ - --resource-group myResourceGroup \ - --name daemoneye \ - --image daemoneye/daemoneye:latest \ - --cpu 1 \ - --memory 2 \ - --ports 8080 9090 \ - --environment-variables DaemonEye_LOG_LEVEL=info -``` - -## Troubleshooting - -### Common Issues - -**Service Won't Start**: - -```bash -# Check service status -sudo systemctl status daemoneye - -# Check logs -sudo journalctl -u daemoneye -f - -# Check configuration -daemoneye-cli config validate -``` - -**Permission Denied**: - -```bash -# Check file permissions -ls -la /var/lib/daemoneye/ -ls -la /var/log/daemoneye/ - -# Fix permissions -sudo chown -R daemoneye:daemoneye /var/lib/daemoneye -sudo chown -R daemoneye:daemoneye /var/log/daemoneye -``` - -**Database Issues**: - -```bash -# Check database status -daemoneye-cli database status - -# Check database integrity -daemoneye-cli database integrity-check - -# Repair database -daemoneye-cli database repair -``` - -**Performance Issues**: - -```bash -# Check system metrics -daemoneye-cli metrics - -# Check resource usage -daemoneye-cli system resources - -# Optimize configuration -daemoneye-cli config optimize -``` - -### Debug Mode - -**Enable Debug Logging**: - -```bash -# Set debug level -daemoneye-cli config set app.log_level debug - -# Restart service -sudo systemctl restart daemoneye - -# Monitor debug logs -daemoneye-cli logs --level debug --tail 100 -``` - -**Debug Specific Components**: - -```bash -# Debug process collection -daemoneye-cli debug collector - -# Debug alert delivery -daemoneye-cli debug alerts - -# Debug database operations -daemoneye-cli debug database -``` - -### Health Checks - -**System Health**: - -```bash -# Overall health -daemoneye-cli health - -# Component health -daemoneye-cli health --component procmond -daemoneye-cli health --component daemoneye-agent -daemoneye-cli health --component database - -# Detailed health report -daemoneye-cli health --verbose -``` - -## Best Practices - -### Deployment - -1. **Start Small**: Begin with basic monitoring and gradually add features -2. **Test Configuration**: Always validate configuration before deployment -3. **Monitor Resources**: Keep an eye on CPU and memory usage -4. **Regular Updates**: Keep DaemonEye updated with latest releases -5. **Backup Data**: Regularly backup configuration and data - -### Security - -1. **Principle of Least Privilege**: Run with minimal required privileges -2. **Network Security**: Use TLS for all network communications -3. **Access Control**: Implement proper authentication and authorization -4. **Audit Logging**: Enable comprehensive audit logging -5. **Regular Updates**: Keep security patches current - -### Performance - -1. **Resource Monitoring**: Monitor CPU, memory, and storage usage -2. **Configuration Tuning**: Optimize configuration for your environment -3. **Load Testing**: Test performance under expected load -4. **Capacity Planning**: Plan for growth and scaling -5. **Regular Maintenance**: Perform regular maintenance and optimization - ---- - -*This deployment documentation provides comprehensive guidance for deploying DaemonEye. For additional help, consult the specific deployment guides or contact support.* diff --git a/docs/src/deployment/configuration.md b/docs/src/deployment/configuration.md deleted file mode 100644 index 4b3203e6..00000000 --- a/docs/src/deployment/configuration.md +++ /dev/null @@ -1,1095 +0,0 @@ -# DaemonEye Configuration Guide - -This guide provides comprehensive configuration instructions for DaemonEye, covering all aspects of system setup, tuning, and customization. - -## Table of Contents - -- [Configuration Overview](#configuration-overview) -- [Configuration Sources](#configuration-sources) -- [Configuration Structure](#configuration-structure) -- [Core Settings](#core-settings) -- [Database Configuration](#database-configuration) -- [Alerting Configuration](#alerting-configuration) -- [Security Configuration](#security-configuration) -- [Performance Tuning](#performance-tuning) -- [Platform-Specific Settings](#platform-specific-settings) -- [Advanced Configuration](#advanced-configuration) -- [Configuration Management](#configuration-management) -- [Troubleshooting](#troubleshooting) - -## Configuration Overview - -DaemonEye uses a hierarchical configuration system that allows for flexible and maintainable settings across different environments and deployment scenarios. - -### Configuration Philosophy - -- **Hierarchical**: Multiple sources with clear precedence -- **Environment-Aware**: Different settings for dev/staging/prod -- **Secure**: Sensitive settings protected and encrypted -- **Validated**: All configuration validated at startup -- **Hot-Reloadable**: Most settings can be updated without restart - -### Configuration Precedence - -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) - -## Configuration Sources - -### Command-Line Flags - -```bash -# Basic configuration -daemoneye-agent --config /path/to/config.yaml --log-level debug - -# Override specific settings -daemoneye-agent --scan-interval 30000 --batch-size 1000 - -# Show effective configuration -daemoneye-cli config show --include-defaults -``` - -### Environment Variables - -```bash -# Set environment variables -export DaemonEye_LOG_LEVEL=debug -export DaemonEye_SCAN_INTERVAL_MS=30000 -export DaemonEye_DATABASE_PATH=/var/lib/daemoneye/processes.db -export DaemonEye_ALERTING_SINKS_0_TYPE=syslog -export DaemonEye_ALERTING_SINKS_0_FACILITY=daemon - -# Run with environment configuration -daemoneye-agent -``` - -### Configuration Files - -**YAML Format** (recommended): - -```yaml -# /etc/daemoneye/config.yaml -app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - data_dir: /var/lib/daemoneye - log_dir: /var/log/daemoneye - -database: - path: /var/lib/daemoneye/processes.db - max_connections: 10 - retention_days: 30 - -alerting: - sinks: - - type: syslog - enabled: true - facility: daemon - - type: webhook - enabled: false - url: https://alerts.example.com/webhook - headers: - Authorization: Bearer ${WEBHOOK_TOKEN} -``` - -**JSON Format**: - -```json -{ - "app": { - "scan_interval_ms": 30000, - "batch_size": 1000, - "log_level": "info", - "data_dir": "/var/lib/daemoneye", - "log_dir": "/var/log/daemoneye" - }, - "database": { - "path": "/var/lib/daemoneye/processes.db", - "max_connections": 10, - "retention_days": 30 - }, - "alerting": { - "sinks": [ - { - "type": "syslog", - "enabled": true, - "facility": "daemon" - } - ] - } -} -``` - -**TOML Format**: - -```toml -[app] -scan_interval_ms = 30000 -batch_size = 1000 -log_level = "info" -data_dir = "/var/lib/daemoneye" -log_dir = "/var/log/daemoneye" - -[database] -path = "/var/lib/daemoneye/processes.db" -max_connections = 10 -retention_days = 30 - -[[alerting.sinks]] -type = "syslog" -enabled = true -facility = "daemon" -``` - -## Configuration Structure - -### Complete Configuration Schema - -```yaml -# Application settings -app: - scan_interval_ms: 30000 # Process scan interval in milliseconds - batch_size: 1000 # Batch size for database operations - log_level: info # Logging level (trace, debug, info, warn, error) - data_dir: /var/lib/daemoneye # Data directory - log_dir: /var/log/daemoneye # Log directory - pid_file: /var/run/daemoneye.pid # PID file location - user: daemoneye # User to run as - group: daemoneye # Group to run as - max_memory_mb: 512 # Maximum memory usage in MB - max_cpu_percent: 5.0 # Maximum CPU usage percentage - -# Database configuration -database: - path: /var/lib/daemoneye/processes.db # Database file path - max_connections: 10 # Maximum database connections - retention_days: 30 # Data retention period - vacuum_interval_hours: 24 # Database vacuum interval - wal_mode: true # Enable WAL mode - synchronous: NORMAL # Synchronous mode - cache_size: -64000 # Cache size in KB (negative = KB) - temp_store: MEMORY # Temporary storage location - journal_mode: WAL # Journal mode - -# Alerting configuration -alerting: - enabled: true # Enable alerting - max_queue_size: 10000 # Maximum alert queue size - delivery_timeout_ms: 5000 # Alert delivery timeout - retry_attempts: 3 # Number of retry attempts - retry_delay_ms: 1000 # Delay between retries - circuit_breaker_threshold: 5 # Circuit breaker failure threshold - circuit_breaker_timeout_ms: 60000 # Circuit breaker timeout - - # Alert sinks - sinks: - - type: syslog # Sink type - enabled: true # Enable this sink - facility: daemon # Syslog facility - priority: info # Syslog priority - tag: daemoneye # Syslog tag - - - type: webhook # Webhook sink - enabled: false # Disabled by default - url: https://alerts.example.com/webhook - method: POST # HTTP method - timeout_ms: 5000 # Request timeout - retry_attempts: 3 # Retry attempts - headers: # Custom headers - Authorization: Bearer ${WEBHOOK_TOKEN} - Content-Type: application/json - template: default # Alert template - - - type: file # File sink - enabled: false # Disabled by default - path: /var/log/daemoneye/alerts.log - format: json # Output format (json, text) - rotation: daily # Log rotation (daily, weekly, monthly) - max_files: 30 # Maximum log files to keep - - - type: stdout # Standard output sink - enabled: false # Disabled by default - format: json # Output format (json, text) - -# Security configuration -security: - enable_privilege_dropping: true # Enable privilege dropping - drop_to_user: daemoneye # User to drop privileges to - drop_to_group: daemoneye # Group to drop privileges to - enable_audit_logging: true # Enable audit logging - audit_log_path: /var/log/daemoneye/audit.log - enable_integrity_checking: true # Enable integrity checking - hash_algorithm: blake3 # Hash algorithm (blake3, sha256) - enable_signature_verification: true # Enable signature verification - public_key_path: /etc/daemoneye/public.key - private_key_path: /etc/daemoneye/private.key - - # Access control - access_control: - allowed_users: [] # Allowed users (empty = all) - allowed_groups: [] # Allowed groups (empty = all) - denied_users: [] # Denied users - denied_groups: [] # Denied groups - - # Network security - network: - enable_tls: false # Enable TLS for network connections - cert_file: /etc/daemoneye/cert.pem - key_file: /etc/daemoneye/key.pem - ca_file: /etc/daemoneye/ca.pem - verify_peer: true # Verify peer certificates - -# Process collection configuration -collection: - enable_process_collection: true # Enable process collection - enable_file_monitoring: false # Enable file monitoring - enable_network_monitoring: false # Enable network monitoring - enable_kernel_monitoring: false # Enable kernel monitoring (Enterprise) - - # Process collection settings - process_collection: - include_children: true # Include child processes - include_threads: false # Include thread information - include_memory_maps: false # Include memory map information - include_file_descriptors: false # Include file descriptor information - max_processes: 10000 # Maximum processes to collect - exclude_patterns: # Process exclusion patterns - - systemd* - - kthreadd* - - ksoftirqd* - - # File monitoring settings - file_monitoring: - watch_directories: [] # Directories to watch - exclude_patterns: # File exclusion patterns - - '*.tmp' - - '*.log' - - '*.cache' - max_file_size_mb: 100 # Maximum file size to monitor - - # Network monitoring settings - network_monitoring: - enable_packet_capture: false # Enable packet capture - capture_interface: any # Network interface to capture - capture_filter: '' # BPF filter expression - max_packet_size: 1500 # Maximum packet size - buffer_size_mb: 100 # Capture buffer size - -# Detection engine configuration -detection: - enable_detection: true # Enable detection engine - rule_directory: /etc/daemoneye/rules # Rules directory - rule_file_pattern: '*.sql' # Rule file pattern - enable_hot_reload: true # Enable hot reloading - reload_interval_ms: 5000 # Reload check interval - max_concurrent_rules: 10 # Maximum concurrent rule executions - rule_timeout_ms: 30000 # Rule execution timeout - enable_rule_caching: true # Enable rule result caching - cache_ttl_seconds: 300 # Cache TTL in seconds - - # Rule execution settings - execution: - enable_parallel_execution: true # Enable parallel rule execution - max_parallel_rules: 5 # Maximum parallel rules - enable_rule_optimization: true # Enable rule optimization - enable_query_planning: true # Enable query planning - - # Alert generation - alert_generation: - enable_alert_deduplication: true # Enable alert deduplication - deduplication_window_ms: 60000 # Deduplication window - enable_alert_aggregation: true # Enable alert aggregation - aggregation_window_ms: 300000 # Aggregation window - max_alerts_per_rule: 1000 # Maximum alerts per rule - -# Observability configuration -observability: - enable_metrics: true # Enable metrics collection - metrics_port: 9090 # Metrics server port - metrics_path: /metrics # Metrics endpoint path - enable_health_checks: true # Enable health checks - health_check_port: 8080 # Health check port - health_check_path: /health # Health check endpoint - - # Tracing configuration - tracing: - enable_tracing: false # Enable distributed tracing - trace_endpoint: http://jaeger:14268/api/traces - trace_sampling_rate: 0.1 # Trace sampling rate - trace_service_name: daemoneye # Service name for traces - - # Logging configuration - logging: - enable_structured_logging: true # Enable structured logging - log_format: json # Log format (json, text) - log_timestamp_format: rfc3339 # Timestamp format - enable_log_rotation: true # Enable log rotation - max_log_file_size_mb: 100 # Maximum log file size - max_log_files: 10 # Maximum log files to keep - - # Performance monitoring - performance: - enable_profiling: false # Enable performance profiling - profile_output_dir: /tmp/daemoneye/profiles - enable_memory_profiling: false # Enable memory profiling - enable_cpu_profiling: false # Enable CPU profiling - -# Platform-specific configuration -platform: - linux: - enable_ebpf: false # Enable eBPF monitoring (Enterprise) - ebpf_program_path: /etc/daemoneye/ebpf/monitor.o - enable_audit: false # Enable Linux audit integration - audit_rules_path: /etc/daemoneye/audit.rules - - windows: - enable_etw: false # Enable ETW monitoring (Enterprise) - etw_session_name: DaemonEye - enable_wmi: false # Enable WMI monitoring - wmi_namespace: root\cimv2 - - macos: - enable_endpoint_security: false # Enable EndpointSecurity (Enterprise) - es_client_name: com.daemoneye.monitor - enable_system_events: false # Enable system event monitoring - -# Integration configuration -integrations: - # SIEM integrations - siem: - splunk: - enabled: false - hec_url: https://splunk.example.com:8088/services/collector - hec_token: ${SPLUNK_HEC_TOKEN} - index: daemoneye - source: daemoneye - sourcetype: daemoneye:processes - - elasticsearch: - enabled: false - url: https://elasticsearch.example.com:9200 - username: ${ELASTIC_USERNAME} - password: ${ELASTIC_PASSWORD} - index: daemoneye-processes - - kafka: - enabled: false - brokers: [kafka1.example.com:9092, kafka2.example.com:9092] - topic: daemoneye.processes - security_protocol: PLAINTEXT - sasl_mechanism: PLAIN - username: ${KAFKA_USERNAME} - password: ${KAFKA_PASSWORD} - - # Export formats - export: - cef: - enabled: false - output_file: /var/log/daemoneye/cef.log - cef_version: '1.0' - device_vendor: DaemonEye - device_product: Process Monitor - device_version: 1.0.0 - - stix: - enabled: false - output_file: /var/log/daemoneye/stix.json - stix_version: '2.1' - stix_id: daemoneye-process-monitor - - json: - enabled: false - output_file: /var/log/daemoneye/events.json - pretty_print: true - include_metadata: true -``` - -## Core Settings - -### Application Settings - -**Basic Configuration**: - -```yaml -app: - scan_interval_ms: 30000 # How often to scan processes (30 seconds) - batch_size: 1000 # Number of processes to process in each batch - log_level: info # Logging verbosity - data_dir: /var/lib/daemoneye # Where to store data files - log_dir: /var/log/daemoneye # Where to store log files -``` - -**Performance Tuning**: - -```yaml -app: - max_memory_mb: 512 # Limit memory usage to 512MB - max_cpu_percent: 5.0 # Limit CPU usage to 5% - scan_interval_ms: 60000 # Reduce scan frequency for lower CPU - batch_size: 500 # Smaller batches for lower memory -``` - -**Security Settings**: - -```yaml -app: - user: daemoneye # Run as non-root user - group: daemoneye # Run as non-root group - pid_file: /var/run/daemoneye.pid # PID file location -``` - -### Logging Configuration - -**Structured Logging**: - -```yaml -observability: - logging: - enable_structured_logging: true - log_format: json - log_timestamp_format: rfc3339 - enable_log_rotation: true - max_log_file_size_mb: 100 - max_log_files: 10 -``` - -**Log Levels**: - -```yaml -app: - log_level: debug # trace, debug, info, warn, error -``` - -**Log Rotation**: - -```yaml -observability: - logging: - enable_log_rotation: true - max_log_file_size_mb: 100 # Rotate when file reaches 100MB - max_log_files: 10 # Keep 10 rotated files -``` - -## Database Configuration - -### SQLite Settings - -**Basic Database Configuration**: - -```yaml -database: - path: /var/lib/daemoneye/processes.db - max_connections: 10 - retention_days: 30 -``` - -**Performance Optimization**: - -```yaml -database: - wal_mode: true # Enable Write-Ahead Logging - synchronous: NORMAL # Balance safety and performance - cache_size: -64000 # 64MB cache (negative = KB) - temp_store: MEMORY # Store temp tables in memory - journal_mode: WAL # Use WAL journal mode -``` - -**Maintenance Settings**: - -```yaml -database: - vacuum_interval_hours: 24 # Vacuum database every 24 hours - retention_days: 30 # Keep data for 30 days - enable_auto_vacuum: true # Enable automatic vacuuming -``` - -### Database Security - -**Access Control**: - -```yaml -database: - enable_encryption: false # Enable database encryption - encryption_key: ${DB_ENCRYPTION_KEY} - enable_access_control: true # Enable access control - allowed_users: [daemoneye] # Allowed database users -``` - -## Alerting Configuration - -### Alert Sinks - -**Syslog Sink**: - -```yaml -alerting: - sinks: - - type: syslog - enabled: true - facility: daemon - priority: info - tag: daemoneye -``` - -**Webhook Sink**: - -```yaml -alerting: - sinks: - - type: webhook - enabled: true - url: https://alerts.example.com/webhook - method: POST - timeout_ms: 5000 - retry_attempts: 3 - headers: - Authorization: Bearer ${WEBHOOK_TOKEN} - Content-Type: application/json -``` - -**File Sink**: - -```yaml -alerting: - sinks: - - type: file - enabled: true - path: /var/log/daemoneye/alerts.log - format: json - rotation: daily - max_files: 30 -``` - -### Alert Processing - -**Deduplication and Aggregation**: - -```yaml -detection: - alert_generation: - enable_alert_deduplication: true - deduplication_window_ms: 60000 - enable_alert_aggregation: true - aggregation_window_ms: 300000 - max_alerts_per_rule: 1000 -``` - -**Delivery Settings**: - -```yaml -alerting: - max_queue_size: 10000 - delivery_timeout_ms: 5000 - retry_attempts: 3 - retry_delay_ms: 1000 - circuit_breaker_threshold: 5 - circuit_breaker_timeout_ms: 60000 -``` - -## Security Configuration - -### Privilege Management - -**Privilege Dropping**: - -```yaml -security: - enable_privilege_dropping: true - drop_to_user: daemoneye - drop_to_group: daemoneye -``` - -**Access Control**: - -```yaml -security: - access_control: - allowed_users: [] # Empty = all users - allowed_groups: [] # Empty = all groups - denied_users: [root] # Deny root user - denied_groups: [wheel] # Deny wheel group -``` - -### Audit and Integrity - -**Audit Logging**: - -```yaml -security: - enable_audit_logging: true - audit_log_path: /var/log/daemoneye/audit.log -``` - -**Integrity Checking**: - -```yaml -security: - enable_integrity_checking: true - hash_algorithm: blake3 - enable_signature_verification: true - public_key_path: /etc/daemoneye/public.key - private_key_path: /etc/daemoneye/private.key -``` - -### Network Security - -**TLS Configuration**: - -```yaml -security: - network: - enable_tls: true - cert_file: /etc/daemoneye/cert.pem - key_file: /etc/daemoneye/key.pem - ca_file: /etc/daemoneye/ca.pem - verify_peer: true -``` - -## Performance Tuning - -### Process Collection - -**Collection Settings**: - -```yaml -collection: - process_collection: - include_children: true - include_threads: false - include_memory_maps: false - include_file_descriptors: false - max_processes: 10000 - exclude_patterns: - - systemd* - - kthreadd* - - ksoftirqd* -``` - -**Performance Optimization**: - -```yaml -app: - scan_interval_ms: 60000 # Reduce scan frequency - batch_size: 500 # Smaller batches - max_memory_mb: 256 # Limit memory usage - max_cpu_percent: 3.0 # Limit CPU usage -``` - -### Database Performance - -**Connection Pooling**: - -```yaml -database: - max_connections: 20 # Increase connection pool - cache_size: -128000 # 128MB cache - temp_store: MEMORY # Use memory for temp tables -``` - -**Query Optimization**: - -```yaml -detection: - execution: - enable_rule_optimization: true - enable_query_planning: true - enable_parallel_execution: true - max_parallel_rules: 5 -``` - -### Memory Management - -**Memory Limits**: - -```yaml -app: - max_memory_mb: 512 # Hard memory limit - max_cpu_percent: 5.0 # CPU usage limit -``` - -**Garbage Collection**: - -```yaml -app: - gc_interval_ms: 300000 # Garbage collection interval - gc_threshold_mb: 100 # GC threshold -``` - -## Platform-Specific Settings - -### Linux Configuration - -**eBPF Monitoring** (Enterprise): - -```yaml -platform: - linux: - enable_ebpf: true - ebpf_program_path: /etc/daemoneye/ebpf/monitor.o - enable_audit: true - audit_rules_path: /etc/daemoneye/audit.rules -``` - -**System Integration**: - -```yaml -platform: - linux: - enable_systemd_integration: true - systemd_unit: daemoneye.service - enable_logrotate: true - logrotate_config: /etc/logrotate.d/daemoneye -``` - -### Windows Configuration - -**ETW Monitoring** (Enterprise): - -```yaml -platform: - windows: - enable_etw: true - etw_session_name: DaemonEye - enable_wmi: true - wmi_namespace: root\cimv2 -``` - -**Service Integration**: - -```yaml -platform: - windows: - service_name: DaemonEye Agent - service_display_name: DaemonEye Security Monitoring Agent - service_description: Monitors system processes for security threats -``` - -### macOS Configuration - -**EndpointSecurity** (Enterprise): - -```yaml -platform: - macos: - enable_endpoint_security: true - es_client_name: com.daemoneye.monitor - enable_system_events: true -``` - -**LaunchDaemon Integration**: - -```yaml -platform: - macos: - launchdaemon_plist: /Library/LaunchDaemons/com.daemoneye.agent.plist - enable_console_logging: true -``` - -## Advanced Configuration - -### Custom Rules - -**Rule Directory**: - -```yaml -detection: - rule_directory: /etc/daemoneye/rules - rule_file_pattern: '*.sql' - enable_hot_reload: true - reload_interval_ms: 5000 -``` - -**Rule Execution**: - -```yaml -detection: - max_concurrent_rules: 10 - rule_timeout_ms: 30000 - enable_rule_caching: true - cache_ttl_seconds: 300 -``` - -### Custom Integrations - -**SIEM Integration**: - -```yaml -integrations: - siem: - splunk: - enabled: true - hec_url: https://splunk.example.com:8088/services/collector - hec_token: ${SPLUNK_HEC_TOKEN} - index: daemoneye - source: daemoneye - sourcetype: daemoneye:processes -``` - -**Export Formats**: - -```yaml -integrations: - export: - cef: - enabled: true - output_file: /var/log/daemoneye/cef.log - cef_version: '1.0' - device_vendor: DaemonEye - device_product: Process Monitor - device_version: 1.0.0 -``` - -### Custom Templates - -**Alert Templates**: - -```yaml -alerting: - templates: - default: | - { - "timestamp": "{{.Timestamp}}", - "rule": "{{.RuleName}}", - "severity": "{{.Severity}}", - "process": { - "pid": {{.Process.PID}}, - "name": "{{.Process.Name}}", - "path": "{{.Process.ExecutablePath}}" - } - } - - syslog: | - {{.Timestamp}} {{.Severity}} {{.RuleName}}: Process {{.Process.Name}} (PID {{.Process.PID}}) triggered alert -``` - -## Configuration Management - -### Configuration Validation - -**Validate Configuration**: - -```bash -# Validate configuration file -daemoneye-cli config validate /path/to/config.yaml - -# Check configuration syntax -daemoneye-cli config check - -# Show effective configuration -daemoneye-cli config show --include-defaults -``` - -**Configuration Testing**: - -```bash -# Test configuration without starting service -daemoneye-agent --config /path/to/config.yaml --dry-run - -# Test specific settings -daemoneye-cli config test --setting app.scan_interval_ms -``` - -### Configuration Updates - -**Hot Reload**: - -```bash -# Reload configuration without restart -daemoneye-cli config reload - -# Update specific setting -daemoneye-cli config set app.scan_interval_ms 60000 - -# Update multiple settings -daemoneye-cli config set app.scan_interval_ms 60000 app.batch_size 500 -``` - -**Configuration Backup**: - -```bash -# Backup current configuration -daemoneye-cli config backup --output /backup/daemoneye-config-$(date +%Y%m%d).yaml - -# Restore configuration -daemoneye-cli config restore --input /backup/daemoneye-config-20240101.yaml -``` - -### Environment Management - -**Development Environment**: - -```yaml -# config-dev.yaml -app: - log_level: debug - scan_interval_ms: 10000 - batch_size: 100 - -database: - path: /tmp/daemoneye-dev.db - retention_days: 1 -``` - -**Production Environment**: - -```yaml -# config-prod.yaml -app: - log_level: info - scan_interval_ms: 60000 - batch_size: 1000 - -database: - path: /var/lib/daemoneye/processes.db - retention_days: 30 -``` - -**Staging Environment**: - -```yaml -# config-staging.yaml -app: - log_level: info - scan_interval_ms: 30000 - batch_size: 500 - -database: - path: /var/lib/daemoneye/processes-staging.db - retention_days: 7 -``` - -## Troubleshooting - -### Configuration Issues - -**Invalid Configuration**: - -```bash -# Check configuration syntax -daemoneye-cli config check - -# Validate configuration -daemoneye-cli config validate - -# Show configuration errors -daemoneye-cli config show --errors -``` - -**Missing Settings**: - -```bash -# Show all settings with defaults -daemoneye-cli config show --include-defaults - -# Show specific setting -daemoneye-cli config get app.scan_interval_ms - -# Set missing setting -daemoneye-cli config set app.scan_interval_ms 30000 -``` - -**Permission Issues**: - -```bash -# Check file permissions -ls -la /etc/daemoneye/config.yaml - -# Fix permissions -sudo chown daemoneye:daemoneye /etc/daemoneye/config.yaml -sudo chmod 644 /etc/daemoneye/config.yaml -``` - -### Performance Issues - -**High CPU Usage**: - -```yaml -# Reduce scan frequency and batch size -app: - scan_interval_ms: 120000 # 2 minutes - batch_size: 250 - -# Exclude more processes -collection: - process_collection: - exclude_patterns: - - systemd* - - kthreadd* - - ksoftirqd* - - migration* - - rcu_* -``` - -**High Memory Usage**: - -```yaml -# Limit memory usage and enable garbage collection -app: - max_memory_mb: 256 - batch_size: 250 - gc_interval_ms: 300000 - gc_threshold_mb: 100 -``` - -**Slow Database Operations**: - -```yaml -# Optimize database settings -database: - cache_size: -128000 # 128MB cache - temp_store: MEMORY - synchronous: NORMAL - wal_mode: true - -# Enable query optimization -detection: - execution: - enable_rule_optimization: true - enable_query_planning: true -``` - -### Debugging Configuration - -**Enable Debug Logging**: - -```yaml -app: - log_level: debug - -observability: - logging: - enable_structured_logging: true - log_format: json -``` - -**Configuration Debugging**: - -```bash -# Show effective configuration -daemoneye-cli config show --include-defaults --format json - -# Test configuration -daemoneye-agent --config /path/to/config.yaml --dry-run - -# Check configuration sources -daemoneye-cli config sources -``` - -**Performance Debugging**: - -```yaml -observability: - performance: - enable_profiling: true - profile_output_dir: /tmp/daemoneye/profiles - enable_memory_profiling: true - enable_cpu_profiling: true -``` - ---- - -*This configuration guide provides comprehensive instructions for configuring DaemonEye. For additional help, consult the troubleshooting section or contact support.* diff --git a/docs/src/deployment/docker.md b/docs/src/deployment/docker.md deleted file mode 100644 index 340b72d4..00000000 --- a/docs/src/deployment/docker.md +++ /dev/null @@ -1,1722 +0,0 @@ -# DaemonEye Docker Deployment Guide - -This guide provides comprehensive instructions for deploying DaemonEye using Docker and Docker Compose, including containerization, orchestration, and production deployment strategies. - ---- - -## Table of Contents - -[TOC] - ---- - -## Docker Overview - -DaemonEye is designed to run efficiently in containerized environments, providing: - -- **Isolation**: Process monitoring within container boundaries -- **Scalability**: Easy horizontal scaling and load balancing -- **Portability**: Consistent deployment across different environments -- **Security**: Container-based privilege isolation -- **Orchestration**: Integration with Kubernetes and other orchestration platforms - -### Container Architecture - -DaemonEye uses a multi-container architecture: - -- **procmond**: Privileged process monitoring daemon -- **daemoneye-agent**: User-space orchestrator and alerting -- **daemoneye-cli**: Command-line interface and management - -## Container Images - -> **NOTE: Docker images are not yet published.** Official Docker images are planned for future releases. For now, please build DaemonEye from source (see [Building from Source](#building-from-source) below). - -### Planned Official Images - -The following Docker images are planned but not yet available: - -**Core Images** (Aspirational): - -```bash -# Process monitoring daemon -docker pull daemoneye/procmond:latest -docker pull daemoneye/procmond:1.0.0 - -# Agent orchestrator -docker pull daemoneye/daemoneye-agent:latest -docker pull daemoneye/daemoneye-agent:1.0.0 - -# CLI interface -docker pull daemoneye/daemoneye-cli:latest -docker pull daemoneye/daemoneye-cli:1.0.0 -``` - -**Planned Image Tags**: - -- `latest`: Latest stable release -- `1.0.0`: Specific version -- `1.0.0-alpine`: Alpine Linux variant (smaller size) -- `1.0.0-debian`: Debian-based variant -- `dev`: Development builds -- `rc-1.0.0`: Release candidate - -### Image Variants - -**Alpine Linux** (Recommended): - -```dockerfile -# Smaller size, security-focused -FROM alpine:3.18 -RUN apk add --no-cache ca-certificates -COPY procmond /usr/local/bin/ -ENTRYPOINT ["procmond"] -``` - -**Debian**: - -```dockerfile -# Full-featured, larger size -FROM debian:bookworm-slim -RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/* -COPY procmond /usr/local/bin/ -ENTRYPOINT ["procmond"] -``` - -**Distroless**: - -```dockerfile -# Minimal attack surface -FROM gcr.io/distroless/cc-debian12 -COPY procmond /usr/local/bin/ -ENTRYPOINT ["procmond"] -``` - -## Building from Source - -Since official Docker images are not yet available, you can build DaemonEye images from the source repository: - -### Clone the Repository - -```bash -git clone https://github.com/EvilBit-Labs/DaemonEye.git -cd DaemonEye -``` - -### Build with Multi-Stage Dockerfile - -Create a `Dockerfile` in the repository root: - -```dockerfile -# Build stage -FROM rust:1.91-bookworm AS builder - -WORKDIR /app -COPY . . - -RUN cargo build --release --bin procmond -RUN cargo build --release --bin daemoneye-agent -RUN cargo build --release --bin daemoneye-cli - -# Runtime stage - procmond -FROM debian:bookworm-slim AS procmond-runtime - -RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/* -COPY --from=builder /app/target/release/procmond /usr/local/bin/procmond - -ENTRYPOINT ["procmond"] - -# Runtime stage - daemoneye-agent -FROM debian:bookworm-slim AS agent-runtime - -RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/* -COPY --from=builder /app/target/release/daemoneye-agent /usr/local/bin/daemoneye-agent - -ENTRYPOINT ["daemoneye-agent"] - -# Runtime stage - daemoneye-cli -FROM debian:bookworm-slim AS cli-runtime - -RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/* -COPY --from=builder /app/target/release/daemoneye-cli /usr/local/bin/daemoneye-cli - -ENTRYPOINT ["daemoneye-cli"] -``` - -### Build Images Locally - -```bash -# Build procmond image -docker build -t daemoneye/procmond:latest \ - --target procmond-runtime \ - . - -# Build daemoneye-agent image (similar approach with different binary) -docker build -t daemoneye/daemoneye-agent:latest \ - --target agent-runtime \ - . - -# Build daemoneye-cli image -docker build -t daemoneye/daemoneye-cli:latest \ - --target cli-runtime \ - . -``` - -### Tag Versions - -```bash -docker tag daemoneye/procmond:latest daemoneye/procmond:1.0.0 -docker tag daemoneye/daemoneye-agent:latest daemoneye/daemoneye-agent:1.0.0 -docker tag daemoneye/daemoneye-cli:latest daemoneye/daemoneye-cli:1.0.0 -``` - -### Verify Built Images - -```bash -# List all built DaemonEye images -docker images daemoneye/* - -# Verify each image runs and reports its version -docker run --rm daemoneye/procmond:latest --version -docker run --rm daemoneye/daemoneye-agent:latest --version -docker run --rm daemoneye/daemoneye-cli:latest --version - -# Inspect image metadata (architecture, size, layers) -docker inspect daemoneye/procmond:latest -docker inspect daemoneye/daemoneye-agent:latest -docker inspect daemoneye/daemoneye-cli:latest -``` - -## Basic Docker Deployment - -> **Note:** The examples below assume Docker images are available. Until official images are published, build images locally from source (see [Building from Source](#building-from-source) above). - -### Single Container Deployment - -**Run Process Monitor**: - -```bash -# Basic run -docker run -d \ - --name daemoneye-procmond \ - --privileged \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - daemoneye/procmond:latest - -# With custom configuration -docker run -d \ - --name daemoneye-procmond \ - --privileged \ - -v /etc/daemoneye:/config \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - -e DaemonEye_LOG_LEVEL=info \ - daemoneye/procmond:latest --config /config/config.yaml -``` - -**Run Agent**: - -```bash -# Basic run -docker run -d \ - --name daemoneye-agent \ - --link daemoneye-procmond:procmond \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - daemoneye/daemoneye-agent:latest - -# With custom configuration -docker run -d \ - --name daemoneye-agent \ - --link daemoneye-procmond:procmond \ - -v /etc/daemoneye:/config \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - -e DaemonEye_LOG_LEVEL=info \ - daemoneye/daemoneye-agent:latest --config /config/config.yaml -``` - -**Run CLI**: - -```bash -# Interactive CLI -docker run -it \ - --rm \ - --link daemoneye-agent:agent \ - -v /var/lib/daemoneye:/data \ - daemoneye/daemoneye-cli:latest - -# Execute specific command -docker run --rm \ - --link daemoneye-agent:agent \ - -v /var/lib/daemoneye:/data \ - daemoneye/daemoneye-cli:latest query "SELECT * FROM processes LIMIT 10" -``` - -### Multi-Container Deployment - -**Create Network**: - -```bash -# Create custom network -docker network create daemoneye-network - -# Run with custom network -docker run -d \ - --name daemoneye-procmond \ - --network daemoneye-network \ - --privileged \ - -v /var/lib/daemoneye:/data \ - daemoneye/procmond:latest - -docker run -d \ - --name daemoneye-agent \ - --network daemoneye-network \ - -v /var/lib/daemoneye:/data \ - daemoneye/daemoneye-agent:latest -``` - -## Docker Compose Deployment - -> **Note:** The examples below use Docker image names. Until official images are published, update the image references to use your locally-built images (e.g., change `daemoneye/procmond:latest` to your local image reference). - -### Basic Docker Compose - -**docker-compose.yml**: - -```yaml -version: '3.8' - -services: - procmond: - image: daemoneye/procmond:latest - container_name: daemoneye-procmond - privileged: true - volumes: - - /var/lib/daemoneye:/data - - /var/log/daemoneye:/logs - - ./config:/config:ro - environment: - - DaemonEye_LOG_LEVEL=info - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - - daemoneye-agent: - image: daemoneye/daemoneye-agent:latest - container_name: daemoneye-agent - depends_on: - - procmond - volumes: - - /var/lib/daemoneye:/data - - /var/log/daemoneye:/logs - - ./config:/config:ro - environment: - - DaemonEye_LOG_LEVEL=info - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - - daemoneye-cli: - image: daemoneye/daemoneye-cli:latest - container_name: daemoneye-cli - depends_on: - - daemoneye-agent - volumes: - - /var/lib/daemoneye:/data - - ./config:/config:ro - environment: - - DaemonEye_DATA_DIR=/data - command: [--help] - restart: no - networks: - - daemoneye-network - -networks: - daemoneye-network: - driver: bridge - -volumes: - daemoneye-data: - driver: local - daemoneye-logs: - driver: local -``` - -### Production Docker Compose - -**docker-compose.prod.yml**: - -```yaml -version: '3.8' - -services: - procmond: - image: daemoneye/procmond:1.0.0 - container_name: daemoneye-procmond - privileged: true - user: 1000:1000 - volumes: - - daemoneye-data:/data - - daemoneye-logs:/logs - - ./config/procmond.yaml:/config/config.yaml:ro - - ./rules:/rules:ro - environment: - - DaemonEye_LOG_LEVEL=info - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - - DaemonEye_RULE_DIR=/rules - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - healthcheck: - test: [CMD, procmond, health] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s - - daemoneye-agent: - image: daemoneye/daemoneye-agent:1.0.0 - container_name: daemoneye-agent - depends_on: - procmond: - condition: service_healthy - user: 1000:1000 - volumes: - - daemoneye-data:/data - - daemoneye-logs:/logs - - ./config/daemoneye-agent.yaml:/config/config.yaml:ro - environment: - - DaemonEye_LOG_LEVEL=info - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - - DaemonEye_PROCMOND_ENDPOINT=tcp://procmond:8080 - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - healthcheck: - test: [CMD, daemoneye-agent, health] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s - - security-center: - image: daemoneye/security-center:1.0.0 - container_name: daemoneye-security-center - depends_on: - daemoneye-agent: - condition: service_healthy - user: 1000:1000 - volumes: - - daemoneye-data:/data - - ./config/security-center.yaml:/config/config.yaml:ro - environment: - - DaemonEye_LOG_LEVEL=info - - DaemonEye_DATA_DIR=/data - - DaemonEye_AGENT_ENDPOINT=tcp://daemoneye-agent:8080 - - DaemonEye_WEB_PORT=8080 - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - ports: - - 8080:8080 - healthcheck: - test: [CMD, curl, -f, http://localhost:8080/health] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s - - nginx: - image: nginx:alpine - container_name: daemoneye-nginx - depends_on: - security-center: - condition: service_healthy - volumes: - - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro - - ./nginx/ssl:/etc/nginx/ssl:ro - ports: - - 80:80 - - 443:443 - restart: unless-stopped - networks: - - daemoneye-network - -networks: - daemoneye-network: - driver: bridge - ipam: - config: - - subnet: 172.20.0.0/16 - -volumes: - daemoneye-data: - driver: local - daemoneye-logs: - driver: local -``` - -### Development Docker Compose - -**docker-compose.dev.yml**: - -```yaml -version: '3.8' - -services: - procmond: - build: - context: . - dockerfile: procmond/Dockerfile - container_name: daemoneye-procmond-dev - privileged: true - volumes: - - ./data:/data - - ./logs:/logs - - ./config:/config:ro - - ./rules:/rules:ro - environment: - - DaemonEye_LOG_LEVEL=debug - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - - DaemonEye_RULE_DIR=/rules - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - - daemoneye-agent: - build: - context: . - dockerfile: daemoneye-agent/Dockerfile - container_name: daemoneye-agent-dev - depends_on: - - procmond - volumes: - - ./data:/data - - ./logs:/logs - - ./config:/config:ro - environment: - - DaemonEye_LOG_LEVEL=debug - - DaemonEye_DATA_DIR=/data - - DaemonEye_LOG_DIR=/logs - - DaemonEye_PROCMOND_ENDPOINT=tcp://procmond:8080 - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - - daemoneye-cli: - build: - context: . - dockerfile: daemoneye-cli/Dockerfile - container_name: daemoneye-cli-dev - depends_on: - - daemoneye-agent - volumes: - - ./data:/data - - ./config:/config:ro - environment: - - DaemonEye_DATA_DIR=/data - command: [--help] - restart: no - networks: - - daemoneye-network - -networks: - daemoneye-network: - driver: bridge -``` - -## Production Deployment - -### Production Configuration - -**Environment Variables**: - -```bash -# .env file -DaemonEye_VERSION=1.0.0 -DaemonEye_LOG_LEVEL=info -DaemonEye_DATA_DIR=/var/lib/daemoneye -DaemonEye_LOG_DIR=/var/log/daemoneye -DaemonEye_CONFIG_DIR=/etc/daemoneye - -# Database settings -DATABASE_PATH=/var/lib/daemoneye/processes.db -DATABASE_RETENTION_DAYS=30 - -# Alerting settings -ALERTING_SYSLOG_ENABLED=true -ALERTING_SYSLOG_FACILITY=daemon -ALERTING_WEBHOOK_ENABLED=false -ALERTING_WEBHOOK_URL=https://alerts.example.com/webhook -ALERTING_WEBHOOK_TOKEN=${WEBHOOK_TOKEN} - -# Security settings -SECURITY_ENABLE_PRIVILEGE_DROPPING=true -SECURITY_DROP_TO_USER=1000 -SECURITY_DROP_TO_GROUP=1000 -SECURITY_ENABLE_AUDIT_LOGGING=true - -# Performance settings -APP_SCAN_INTERVAL_MS=60000 -APP_BATCH_SIZE=1000 -APP_MAX_MEMORY_MB=512 -APP_MAX_CPU_PERCENT=5.0 -``` - -**Production Docker Compose**: - -```yaml -version: '3.8' - -services: - procmond: - image: daemoneye/procmond:${DaemonEye_VERSION} - container_name: daemoneye-procmond - privileged: true - user: ${SECURITY_DROP_TO_USER}:${SECURITY_DROP_TO_GROUP} - volumes: - - daemoneye-data:/data - - daemoneye-logs:/logs - - ./config/procmond.yaml:/config/config.yaml:ro - - ./rules:/rules:ro - environment: - - DaemonEye_LOG_LEVEL=${DaemonEye_LOG_LEVEL} - - DaemonEye_DATA_DIR=${DaemonEye_DATA_DIR} - - DaemonEye_LOG_DIR=${DaemonEye_LOG_DIR} - - DaemonEye_RULE_DIR=/rules - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - healthcheck: - test: [CMD, procmond, health] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s - logging: - driver: json-file - options: - max-size: 100m - max-file: '5' - - daemoneye-agent: - image: daemoneye/daemoneye-agent:${DaemonEye_VERSION} - container_name: daemoneye-agent - depends_on: - procmond: - condition: service_healthy - user: ${SECURITY_DROP_TO_USER}:${SECURITY_DROP_TO_GROUP} - volumes: - - daemoneye-data:/data - - daemoneye-logs:/logs - - ./config/daemoneye-agent.yaml:/config/config.yaml:ro - environment: - - DaemonEye_LOG_LEVEL=${DaemonEye_LOG_LEVEL} - - DaemonEye_DATA_DIR=${DaemonEye_DATA_DIR} - - DaemonEye_LOG_DIR=${DaemonEye_LOG_DIR} - - DaemonEye_PROCMOND_ENDPOINT=tcp://procmond:8080 - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - healthcheck: - test: [CMD, daemoneye-agent, health] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s - logging: - driver: json-file - options: - max-size: 100m - max-file: '5' - - security-center: - image: daemoneye/security-center:${DaemonEye_VERSION} - container_name: daemoneye-security-center - depends_on: - daemoneye-agent: - condition: service_healthy - user: ${SECURITY_DROP_TO_USER}:${SECURITY_DROP_TO_GROUP} - volumes: - - daemoneye-data:/data - - ./config/security-center.yaml:/config/config.yaml:ro - environment: - - DaemonEye_LOG_LEVEL=${DaemonEye_LOG_LEVEL} - - DaemonEye_DATA_DIR=${DaemonEye_DATA_DIR} - - DaemonEye_AGENT_ENDPOINT=tcp://daemoneye-agent:8080 - - DaemonEye_WEB_PORT=8080 - command: [--config, /config/config.yaml] - restart: unless-stopped - networks: - - daemoneye-network - ports: - - 8080:8080 - healthcheck: - test: [CMD, curl, -f, http://localhost:8080/health] - interval: 30s - timeout: 10s - retries: 3 - start_period: 40s - logging: - driver: json-file - options: - max-size: 100m - max-file: '5' - -networks: - daemoneye-network: - driver: bridge - ipam: - config: - - subnet: 172.20.0.0/16 - -volumes: - daemoneye-data: - driver: local - daemoneye-logs: - driver: local -``` - -### Deployment Scripts - -**deploy.sh**: - -```bash -#!/bin/bash - -set -e - -# Configuration -COMPOSE_FILE="docker-compose.prod.yml" -ENV_FILE=".env" -BACKUP_DIR="/backup/daemoneye" -LOG_DIR="/var/log/daemoneye" - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -NC='\033[0m' # No Color - -# Functions -log_info() { - echo -e "${GREEN}[INFO]${NC} $1" -} - -log_warn() { - echo -e "${YELLOW}[WARN]${NC} $1" -} - -log_error() { - echo -e "${RED}[ERROR]${NC} $1" -} - -# Check prerequisites -check_prerequisites() { - log_info "Checking prerequisites..." - - if ! command -v docker &> /dev/null; then - log_error "Docker is not installed" - exit 1 - fi - - if ! command -v docker-compose &> /dev/null; then - log_error "Docker Compose is not installed" - exit 1 - fi - - if [ ! -f "$ENV_FILE" ]; then - log_error "Environment file $ENV_FILE not found" - exit 1 - fi - - if [ ! -f "$COMPOSE_FILE" ]; then - log_error "Compose file $COMPOSE_FILE not found" - exit 1 - fi - - log_info "Prerequisites check passed" -} - -# Backup existing deployment -backup_deployment() { - log_info "Backing up existing deployment..." - - if [ -d "$BACKUP_DIR" ]; then - rm -rf "$BACKUP_DIR" - fi - - mkdir -p "$BACKUP_DIR" - - # Backup data volumes - if docker volume ls | grep -q daemoneye-data; then - docker run --rm -v daemoneye-data:/data -v "$BACKUP_DIR":/backup alpine tar czf /backup/data.tar.gz -C /data . - fi - - # Backup logs - if [ -d "$LOG_DIR" ]; then - cp -r "$LOG_DIR" "$BACKUP_DIR/logs" - fi - - log_info "Backup completed" -} - -# Deploy DaemonEye -deploy_daemoneye() { - log_info "Deploying DaemonEye..." - - # Pull latest images - docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" pull - - # Stop existing services - docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" down - - # Start services - docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" up -d - - # Wait for services to be healthy - log_info "Waiting for services to be healthy..." - sleep 30 - - # Check service health - if docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" ps | grep -q "unhealthy"; then - log_error "Some services are unhealthy" - docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" logs - exit 1 - fi - - log_info "Deployment completed successfully" -} - -# Main execution -main() { - log_info "Starting DaemonEye deployment..." - - check_prerequisites - backup_deployment - deploy_daemoneye - - log_info "DaemonEye deployment completed successfully" -} - -# Run main function -main "$@" -``` - -**rollback.sh**: - -```bash -#!/bin/bash - -set -e - -# Configuration -COMPOSE_FILE="docker-compose.prod.yml" -ENV_FILE=".env" -BACKUP_DIR="/backup/daemoneye" - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -NC='\033[0m' # No Color - -# Functions -log_info() { - echo -e "${GREEN}[INFO]${NC} $1" -} - -log_warn() { - echo -e "${YELLOW}[WARN]${NC} $1" -} - -log_error() { - echo -e "${RED}[ERROR]${NC} $1" -} - -# Rollback deployment -rollback_deployment() { - log_info "Rolling back DaemonEye deployment..." - - # Stop current services - docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" down - - # Restore data volumes - if [ -f "$BACKUP_DIR/data.tar.gz" ]; then - docker run --rm -v daemoneye-data:/data -v "$BACKUP_DIR":/backup alpine tar xzf /backup/data.tar.gz -C /data - fi - - # Restore logs - if [ -d "$BACKUP_DIR/logs" ]; then - cp -r "$BACKUP_DIR/logs"/* /var/log/daemoneye/ - fi - - # Start services - docker-compose -f "$COMPOSE_FILE" --env-file "$ENV_FILE" up -d - - log_info "Rollback completed" -} - -# Main execution -main() { - log_info "Starting DaemonEye rollback..." - - rollback_deployment - - log_info "DaemonEye rollback completed successfully" -} - -# Run main function -main "$@" -``` - -## Kubernetes Deployment - -> **Note:** The Kubernetes manifests below reference Docker images. Until official images are published, you must either: -> -> 1. Build images locally and push to your container registry, then update image references in manifests -> 2. Use imagePullPolicy: Never and pre-load images on cluster nodes - -### Kubernetes Manifests - -**Namespace**: - -```yaml -# namespace.yaml -apiVersion: v1 -kind: Namespace -metadata: - name: daemoneye - labels: - name: daemoneye -``` - -**ConfigMap**: - -```yaml -# configmap.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: daemoneye-config - namespace: daemoneye -data: - procmond.yaml: | - app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - data_dir: /data - log_dir: /logs - database: - path: /data/processes.db - retention_days: 30 - security: - enable_privilege_dropping: true - drop_to_user: 1000 - drop_to_group: 1000 - - daemoneye-agent.yaml: | - app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - data_dir: /data - log_dir: /logs - database: - path: /data/processes.db - retention_days: 30 - alerting: - enabled: true - sinks: - - type: syslog - enabled: true - facility: daemon - - type: webhook - enabled: true - url: http://daemoneye-webhook:8080/webhook -``` - -**Secret**: - -```yaml -# secret.yaml -apiVersion: v1 -kind: Secret -metadata: - name: daemoneye-secrets - namespace: daemoneye -type: Opaque -data: - webhook-token: - database-encryption-key: -``` - -**PersistentVolumeClaim**: - -```yaml -# pvc.yaml -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: daemoneye-data - namespace: daemoneye -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi - storageClassName: fast-ssd -``` - -**DaemonSet for procmond**: - -```yaml -# procmond-daemonset.yaml -apiVersion: apps/v1 -kind: DaemonSet -metadata: - name: daemoneye-procmond - namespace: daemoneye -spec: - selector: - matchLabels: - app: daemoneye-procmond - template: - metadata: - labels: - app: daemoneye-procmond - spec: - serviceAccountName: daemoneye-procmond - containers: - - name: procmond - image: daemoneye/procmond:1.0.0 - imagePullPolicy: IfNotPresent - securityContext: - privileged: true - runAsUser: 1000 - runAsGroup: 1000 - volumeMounts: - - name: config - mountPath: /config - readOnly: true - - name: data - mountPath: /data - - name: logs - mountPath: /logs - - name: rules - mountPath: /rules - readOnly: true - env: - - name: DaemonEye_LOG_LEVEL - value: info - - name: DaemonEye_DATA_DIR - value: /data - - name: DaemonEye_LOG_DIR - value: /logs - command: [procmond] - args: [--config, /config/procmond.yaml] - resources: - requests: - memory: 256Mi - cpu: 100m - limits: - memory: 512Mi - cpu: 500m - livenessProbe: - exec: - command: - - procmond - - health - initialDelaySeconds: 30 - periodSeconds: 30 - timeoutSeconds: 10 - failureThreshold: 3 - readinessProbe: - exec: - command: - - procmond - - health - initialDelaySeconds: 10 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 3 - volumes: - - name: config - configMap: - name: daemoneye-config - - name: data - persistentVolumeClaim: - claimName: daemoneye-data - - name: logs - emptyDir: {} - - name: rules - configMap: - name: daemoneye-rules - tolerations: - - key: node-role.kubernetes.io/master - operator: Exists - effect: NoSchedule - - key: node-role.kubernetes.io/control-plane - operator: Exists - effect: NoSchedule -``` - -**Deployment for daemoneye-agent**: - -```yaml -# daemoneye-agent-deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: daemoneye-agent - namespace: daemoneye -spec: - replicas: 1 - selector: - matchLabels: - app: daemoneye-agent - template: - metadata: - labels: - app: daemoneye-agent - spec: - serviceAccountName: daemoneye-agent - containers: - - name: daemoneye-agent - image: daemoneye/daemoneye-agent:1.0.0 - imagePullPolicy: IfNotPresent - securityContext: - runAsUser: 1000 - runAsGroup: 1000 - volumeMounts: - - name: config - mountPath: /config - readOnly: true - - name: data - mountPath: /data - - name: logs - mountPath: /logs - env: - - name: DaemonEye_LOG_LEVEL - value: info - - name: DaemonEye_DATA_DIR - value: /data - - name: DaemonEye_LOG_DIR - value: /logs - - name: DaemonEye_PROCMOND_ENDPOINT - value: tcp://daemoneye-procmond:8080 - command: [daemoneye-agent] - args: [--config, /config/daemoneye-agent.yaml] - resources: - requests: - memory: 512Mi - cpu: 200m - limits: - memory: 1Gi - cpu: 1000m - livenessProbe: - exec: - command: - - daemoneye-agent - - health - initialDelaySeconds: 30 - periodSeconds: 30 - timeoutSeconds: 10 - failureThreshold: 3 - readinessProbe: - exec: - command: - - daemoneye-agent - - health - initialDelaySeconds: 10 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 3 - volumes: - - name: config - configMap: - name: daemoneye-config - - name: data - persistentVolumeClaim: - claimName: daemoneye-data - - name: logs - emptyDir: {} -``` - -**Service**: - -```yaml -# service.yaml -apiVersion: v1 -kind: Service -metadata: - name: daemoneye-agent - namespace: daemoneye -spec: - selector: - app: daemoneye-agent - ports: - - name: http - port: 8080 - targetPort: 8080 - protocol: TCP - type: ClusterIP -``` - -**ServiceAccount and RBAC**: - -```yaml -# rbac.yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: daemoneye-procmond - namespace: daemoneye ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: daemoneye-agent - namespace: daemoneye ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: daemoneye-procmond -rules: -- apiGroups: [""] - resources: ["nodes", "pods"] - verbs: ["get", "list", "watch"] -- apiGroups: [""] - resources: ["pods/exec"] - verbs: ["create"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: daemoneye-procmond -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: daemoneye-procmond -subjects: -- kind: ServiceAccount - name: daemoneye-procmond - namespace: daemoneye ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: daemoneye-agent -rules: -- apiGroups: [""] - resources: ["pods", "services", "endpoints"] - verbs: ["get", "list", "watch"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: daemoneye-agent -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: daemoneye-agent -subjects: -- kind: ServiceAccount - name: daemoneye-agent - namespace: daemoneye -``` - -### Helm Chart - -**Chart.yaml**: - -```yaml -# Chart.yaml -apiVersion: v2 -name: daemoneye -description: DaemonEye Security Monitoring Agent -type: application -version: 1.0.0 -appVersion: 1.0.0 -keywords: - - security - - monitoring - - processes - - threat-detection -home: https://daemoneye.com -sources: - - https://github.com/daemoneye/daemoneye -maintainers: - - name: DaemonEye Team - email: team@daemoneye.com -``` - -**values.yaml**: - -```yaml -# values.yaml -image: - repository: daemoneye - tag: 1.0.0 - pullPolicy: IfNotPresent - -replicaCount: 1 - -serviceAccount: - create: true - annotations: {} - name: '' - -podSecurityContext: - runAsUser: 1000 - runAsGroup: 1000 - fsGroup: 1000 - -securityContext: - allowPrivilegeEscalation: false - capabilities: - drop: - - ALL - readOnlyRootFilesystem: true - runAsNonRoot: true - runAsUser: 1000 - -service: - type: ClusterIP - port: 8080 - -ingress: - enabled: false - className: '' - annotations: {} - hosts: - - host: daemoneye.example.com - paths: - - path: / - pathType: Prefix - tls: [] - -resources: - limits: - cpu: 1000m - memory: 1Gi - requests: - cpu: 200m - memory: 512Mi - -autoscaling: - enabled: false - minReplicas: 1 - maxReplicas: 10 - targetCPUUtilizationPercentage: 80 - targetMemoryUtilizationPercentage: 80 - -nodeSelector: {} - -tolerations: [] - -affinity: {} - -persistence: - enabled: true - storageClass: '' - accessMode: ReadWriteOnce - size: 10Gi - -config: - app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - database: - retention_days: 30 - alerting: - enabled: true - sinks: - - type: syslog - enabled: true - facility: daemon - -secrets: {} - -monitoring: - enabled: false - serviceMonitor: - enabled: false - namespace: '' - interval: 30s - scrapeTimeout: 10s -``` - -## Security Considerations - -### Container Security - -**Security Context**: - -```yaml -securityContext: - runAsUser: 1000 - runAsGroup: 1000 - runAsNonRoot: true - allowPrivilegeEscalation: false - readOnlyRootFilesystem: true - capabilities: - drop: - - ALL - add: - - CAP_SYS_PTRACE # Only for procmond -``` - -**Privileged Containers**: - -```yaml -# Only procmond needs privileged access -securityContext: - privileged: true - capabilities: - add: - - CAP_SYS_PTRACE - - CAP_SYS_ADMIN -``` - -**Network Security**: - -```yaml -# Network policies -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: daemoneye-network-policy - namespace: daemoneye -spec: - podSelector: - matchLabels: - app: daemoneye - policyTypes: - - Ingress - - Egress - ingress: - - from: - - namespaceSelector: - matchLabels: - name: daemoneye - ports: - - protocol: TCP - port: 8080 - egress: - - to: - - namespaceSelector: - matchLabels: - name: daemoneye - ports: - - protocol: TCP - port: 8080 -``` - -### Image Security - -**Image Scanning**: - -```bash -# Scan images for vulnerabilities -docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ - aquasec/trivy image daemoneye/procmond:1.0.0 - -# Scan with specific severity levels -docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ - aquasec/trivy image --severity HIGH,CRITICAL daemoneye/procmond:1.0.0 -``` - -**Image Signing**: - -```bash -# Sign images with Docker Content Trust -export DOCKER_CONTENT_TRUST=1 -docker push daemoneye/procmond:1.0.0 -``` - -**Multi-stage Builds**: - -```dockerfile -# Multi-stage build for smaller attack surface -FROM rust:1.91-alpine AS builder -WORKDIR /app -COPY . . -RUN cargo build --release - -FROM alpine:3.18 -RUN apk add --no-cache ca-certificates -COPY --from=builder /app/target/release/procmond /usr/local/bin/ -USER 1000:1000 -ENTRYPOINT ["procmond"] -``` - -## Monitoring and Logging - -### Container Monitoring - -**Prometheus Metrics**: - -```yaml -# Enable metrics collection -observability: - enable_metrics: true - metrics_port: 9090 - metrics_path: /metrics -``` - -**Grafana Dashboard**: - -```json -{ - "dashboard": { - "title": "DaemonEye Monitoring", - "panels": [ - { - "title": "Process Collection Rate", - "type": "graph", - "targets": [ - { - "expr": "rate(daemoneye_processes_collected_total[5m])", - "legendFormat": "Processes/sec" - } - ] - }, - { - "title": "Memory Usage", - "type": "graph", - "targets": [ - { - "expr": "daemoneye_memory_usage_bytes", - "legendFormat": "Memory Usage" - } - ] - } - ] - } -} -``` - -### Log Aggregation - -**Fluentd Configuration**: - -```yaml -# fluentd-configmap.yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: fluentd-config - namespace: daemoneye -data: - fluent.conf: | - - @type tail - path /var/log/daemoneye/*.log - pos_file /var/log/fluentd/daemoneye.log.pos - tag daemoneye.* - format json - - - - @type elasticsearch - host elasticsearch.logging.svc.cluster.local - port 9200 - index_name daemoneye - type_name _doc - -``` - -**ELK Stack Integration**: - -```yaml -# elasticsearch-deployment.yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: elasticsearch - namespace: logging -spec: - replicas: 1 - selector: - matchLabels: - app: elasticsearch - template: - metadata: - labels: - app: elasticsearch - spec: - containers: - - name: elasticsearch - image: docker.elastic.co/elasticsearch/elasticsearch:8.8.0 - env: - - name: discovery.type - value: single-node - - name: xpack.security.enabled - value: 'false' - ports: - - containerPort: 9200 - resources: - requests: - memory: 1Gi - cpu: 500m - limits: - memory: 2Gi - cpu: 1000m -``` - -## Troubleshooting - -### Common Issues - -**Container Won't Start**: - -```bash -# Check container logs -docker logs daemoneye-procmond - -# Check container status -docker ps -a - -# Check resource usage -docker stats daemoneye-procmond -``` - -**Permission Denied**: - -```bash -# Check file permissions -docker exec daemoneye-procmond ls -la /data - -# Fix permissions -docker exec daemoneye-procmond chown -R 1000:1000 /data -``` - -**Network Issues**: - -```bash -# Check network connectivity -docker exec daemoneye-agent ping daemoneye-procmond - -# Check DNS resolution -docker exec daemoneye-agent nslookup daemoneye-procmond -``` - -**Database Issues**: - -```bash -# Check database status -docker exec daemoneye-agent daemoneye-cli database status - -# Check database integrity -docker exec daemoneye-agent daemoneye-cli database integrity-check - -# Repair database -docker exec daemoneye-agent daemoneye-cli database repair -``` - -### Debug Mode - -**Enable Debug Logging**: - -```yaml -# docker-compose.yml -services: - procmond: - environment: - - DaemonEye_LOG_LEVEL=debug - command: [procmond, --config, /config/config.yaml, --log-level, debug] -``` - -**Debug Container**: - -```bash -# Run debug container -docker run -it --rm --privileged \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - daemoneye/procmond:latest /bin/sh - -# Check system capabilities -docker run --rm --privileged daemoneye/procmond:latest capsh --print -``` - -### Performance Issues - -**High CPU Usage**: - -```bash -# Check CPU usage -docker stats daemoneye-procmond - -# Reduce scan frequency -docker exec daemoneye-procmond daemoneye-cli config set app.scan_interval_ms 120000 -``` - -**High Memory Usage**: - -```bash -# Check memory usage -docker stats daemoneye-procmond - -# Limit memory usage -docker run -d --memory=512m daemoneye/procmond:latest -``` - -**Slow Database Operations**: - -```bash -# Check database performance -docker exec daemoneye-agent daemoneye-cli database query-stats - -# Optimize database -docker exec daemoneye-agent daemoneye-cli database optimize -``` - -### Health Checks - -**Container Health**: - -```bash -# Check container health -docker inspect daemoneye-procmond | jq '.[0].State.Health' - -# Run health check manually -docker exec daemoneye-procmond procmond health -``` - -**Service Health**: - -```bash -# Check service health -curl http://localhost:8080/health - -# Check metrics -curl http://localhost:9090/metrics -``` - ---- - -*This Docker deployment guide provides comprehensive instructions for containerizing and deploying DaemonEye. For additional help, consult the troubleshooting section or contact support.* diff --git a/docs/src/deployment/installation.md b/docs/src/deployment/installation.md deleted file mode 100644 index 016d8d07..00000000 --- a/docs/src/deployment/installation.md +++ /dev/null @@ -1,759 +0,0 @@ -# DaemonEye Installation Guide - -This guide provides comprehensive installation instructions for DaemonEye across different platforms and deployment scenarios. - ---- - -## Table of Contents - -[TOC] - ---- - -## System Requirements - -### Minimum Requirements - -**Operating System**: - -- Linux: Ubuntu 20.04+ LTS, RHEL/CentOS 8+, Debian 11+ -- macOS: 14.0+ (Sonoma or later) -- Windows: Windows 10+, Server 2019+ - -**Hardware**: - -- CPU: x86_64 or ARM64 processor -- RAM: 512MB available memory -- Disk: 1GB free space -- Network: Internet access for initial setup (optional) - -**Privileges**: - -- Linux: `CAP_SYS_PTRACE` capability or root access -- Windows: `SeDebugPrivilege` or Administrator access -- macOS: Appropriate entitlements or root access - -### Recommended Requirements - -**Operating System**: - -- Linux: Kernel 4.15+ (Ubuntu 18.04+, RHEL 8+, Debian 10+) -- macOS: 11+ (Big Sur or later) -- Windows: Windows 11+ or Windows Server 2019+ - -**Hardware**: - -- CPU: 2+ cores -- RAM: 2GB+ available memory -- Disk: 10GB+ free space -- Network: Stable internet connection - -## Installation Methods - -### Method 1: Pre-built Binaries (Recommended) - -**Download Latest Release**: - -```bash -# 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 x86_64 -curl -L https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/daemoneye-macos-x86_64.tar.gz | tar -xz - -# macOS ARM64 (Apple Silicon) -curl -L https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/daemoneye-macos-aarch64.tar.gz | tar -xz - -# Windows x86_64 -# Download from GitHub releases and extract -``` - -**Install to System Directories**: - -```bash -# 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 - -# Create system directories -sudo mkdir -p /etc/daemoneye -sudo mkdir -p /var/lib/daemoneye -sudo mkdir -p /var/log/daemoneye - -# Set ownership -sudo chown -R $USER:$USER /etc/daemoneye -sudo chown -R $USER:$USER /var/lib/daemoneye -sudo chown -R $USER:$USER /var/log/daemoneye - -# Windows -# Copy to C:\Program Files\DaemonEye\ -# Add to PATH environment variable -``` - -### Method 2: Package Managers *(Planned)* - -> **Status: Not yet available.** Package manager support (Homebrew, APT, YUM/DNF, Chocolatey) is under development and will be available in a future release. - -For now, use one of the following installation methods: - -- **Pre-built Binaries** (Method 1) - Recommended for most users -- **Build from Source** (Method 3) - For developers and advanced users - -### Method 3: Build from Source - -**Install Rust** (1.91+): - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -source ~/.cargo/env -rustup update -``` - -**Clone and Build**: - -```bash -# Clone repository -git clone https://github.com/EvilBit-Labs/DaemonEye.git -cd DaemonEye - -# Build in release mode -cargo build --release - -# Install built binaries -sudo cp target/release/procmond target/release/daemoneye-agent target/release/daemoneye-cli /usr/local/bin/ -sudo chmod +x /usr/local/bin/procmond /usr/local/bin/daemoneye-agent /usr/local/bin/daemoneye-cli -``` - -**Cross-Platform Building**: - -```bash -# Install cross-compilation toolchain -rustup target add x86_64-unknown-linux-gnu -rustup target add aarch64-unknown-linux-gnu -rustup target add x86_64-apple-darwin -rustup target add aarch64-apple-darwin - -# Build for different targets -cargo build --release --target x86_64-unknown-linux-gnu -cargo build --release --target aarch64-unknown-linux-gnu -cargo build --release --target x86_64-apple-darwin -cargo build --release --target aarch64-apple-darwin -``` - -### Method 4: Using GoReleaser (Release Tooling) - -DaemonEye uses [GoReleaser](https://goreleaser.com/) for automated cross-platform building, packaging, and releasing. This is the recommended method for developers and contributors who want to build release-quality binaries. - -**Local build with GoReleaser**: - -```bash -# Validate configuration -just goreleaser-check - -# Build binaries locally (snapshot, no publish) -just goreleaser-build - -# Run a full snapshot release (build + package, no publish) -just goreleaser-snapshot -``` - -**Release with cargo-release**: - -```bash -# Dry run to see what would be changed -cargo release --dry-run - -# Prepare a new release (updates version, creates tag) -cargo release --execute - -# Release with specific version -cargo release 1.0.0 --execute -``` - -**GoReleaser Configuration**: - -The project includes platform-specific GoReleaser configs (`.goreleaser-linux.yaml`, `.goreleaser-macos.yaml`, `.goreleaser-windows.yaml`) that define: - -- **Supported platforms**: Linux (x86_64, aarch64), macOS (x86_64, aarch64), Windows (x86_64, aarch64) -- **Package formats**: `.tar.gz` for Unix, `.zip` for Windows -- **Binaries**: procmond, daemoneye-agent, daemoneye-cli -- **Signing**: Cosign keyless signing via GitHub Actions OIDC - -**Release Workflow**: - -```bash -# 1. Update version and create tag -cargo release --execute - -# 2. Push tag to trigger CI release -git push --tags - -# 3. GoReleaser builds, packages, signs, and publishes to GitHub Releases -``` - -> [!NOTE] -> **For Contributors**: Use `just goreleaser-build` to create release-quality binaries that match the official distribution format. - -## Platform-Specific Installation - -### Linux Installation - -**Ubuntu/Debian - Build from Source**: - -```bash -# Update system -sudo apt update && sudo apt upgrade -y - -# Install dependencies -sudo apt install -y ca-certificates curl wget build-essential - -# Install Rust -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -source ~/.cargo/env - -# Clone and build -git clone https://github.com/EvilBit-Labs/DaemonEye.git -cd DaemonEye -cargo build --release - -# Install binaries -sudo cp target/release/procmond target/release/daemoneye-agent target/release/daemoneye-cli /usr/local/bin/ -sudo chmod +x /usr/local/bin/procmond /usr/local/bin/daemoneye-agent /usr/local/bin/daemoneye-cli - -# Create system directories -sudo mkdir -p /etc/daemoneye /var/lib/daemoneye /var/log/daemoneye -sudo chown -R $USER:$USER /etc/daemoneye /var/lib/daemoneye /var/log/daemoneye - -# Configure service -sudo systemctl enable daemoneye -sudo systemctl start daemoneye -``` - -**RHEL/CentOS - Build from Source**: - -```bash -# Update system -sudo yum update -y - -# Install dependencies -sudo yum install -y ca-certificates curl wget gcc g++ make - -# Install Rust -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -source ~/.cargo/env - -# Clone and build -git clone https://github.com/EvilBit-Labs/DaemonEye.git -cd DaemonEye -cargo build --release - -# Install binaries -sudo cp target/release/procmond target/release/daemoneye-agent target/release/daemoneye-cli /usr/local/bin/ -sudo chmod +x /usr/local/bin/procmond /usr/local/bin/daemoneye-agent /usr/local/bin/daemoneye-cli - -# Create system directories -sudo mkdir -p /etc/daemoneye /var/lib/daemoneye /var/log/daemoneye -sudo chown -R $USER:$USER /etc/daemoneye /var/lib/daemoneye /var/log/daemoneye - -# Configure service -sudo systemctl enable daemoneye -sudo systemctl start daemoneye -``` - -**Arch Linux - Build from Source**: - -```bash -# Install dependencies -sudo pacman -S --needed base-devel rust - -# Clone and build -git clone https://github.com/EvilBit-Labs/DaemonEye.git -cd DaemonEye -cargo build --release - -# Install binaries -sudo install -Dm755 target/release/procmond /usr/local/bin/procmond -sudo install -Dm755 target/release/daemoneye-agent /usr/local/bin/daemoneye-agent -sudo install -Dm755 target/release/daemoneye-cli /usr/local/bin/daemoneye-cli - -# Create system directories -sudo mkdir -p /etc/daemoneye /var/lib/daemoneye /var/log/daemoneye -``` - -### macOS Installation - -**Using Homebrew** *(Planned)*: - -Homebrew package support for DaemonEye is coming soon. For now, please use the build from source or manual installation methods below. - -**Build from Source**: - -```bash -# Clone the repository -git clone https://github.com/EvilBit-Labs/DaemonEye.git -cd DaemonEye - -# Install Rust if not already installed -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -source "$HOME/.cargo/env" - -# Build DaemonEye -cargo build --release - -# Install binaries (macOS-compatible: mkdir -p + install -m 755) -sudo mkdir -p /usr/local/bin -sudo install -m 755 target/release/procmond /usr/local/bin/procmond -sudo install -m 755 target/release/daemoneye-agent /usr/local/bin/daemoneye-agent -sudo install -m 755 target/release/daemoneye-cli /usr/local/bin/daemoneye-cli - -# Create system directories -sudo mkdir -p /etc/daemoneye /var/lib/daemoneye /var/log/daemoneye -``` - -**Manual Installation**: - -```bash -# Download and extract -curl -L https://github.com/EvilBit-Labs/DaemonEye/releases/latest/download/daemoneye-macos-x86_64.tar.gz | tar -xz - -# Install to system directories -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 - -# Create directories -sudo mkdir -p /Library/Application\ Support/DaemonEye -sudo mkdir -p /var/lib/daemoneye -sudo mkdir -p /var/log/daemoneye - -# Set ownership -sudo chown -R $(whoami):staff /Library/Application\ Support/DaemonEye -sudo chown -R $(whoami):staff /var/lib/daemoneye -sudo chown -R $(whoami):staff /var/log/daemoneye -``` - -### Windows Installation - -**Using Chocolatey** *(Planned)*: - -Chocolatey package support for DaemonEye is coming soon. For now, please use the build from source or manual installation methods below. - -**Build from Source**: - -```powershell -# Install Rust (from https://rustup.rs/) -# Download and run rustup-init.exe, or use: -# iwr https://static.rust-lang.org/rustup/dist/x86_64-pc-windows-msvc/rustup-init.exe -OutFile rustup-init.exe -# .\rustup-init.exe -y - -# Clone the repository -git clone https://github.com/EvilBit-Labs/DaemonEye.git -cd DaemonEye - -# Build DaemonEye -cargo build --release - -# Create installation directory -New-Item -ItemType Directory -Path "C:\Program Files\DaemonEye" -Force - -# Install binaries -Copy-Item "target\release\procmond.exe" "C:\Program Files\DaemonEye\" -Copy-Item "target\release\daemoneye-agent.exe" "C:\Program Files\DaemonEye\" -Copy-Item "target\release\daemoneye-cli.exe" "C:\Program Files\DaemonEye\" - -# Add to PATH (run as Administrator) -[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\Program Files\DaemonEye", [EnvironmentVariableTarget]::Machine) - -# Create data directories -New-Item -ItemType Directory -Path "C:\ProgramData\DaemonEye" -Force -New-Item -ItemType Directory -Path "C:\ProgramData\DaemonEye\data" -Force -New-Item -ItemType Directory -Path "C:\ProgramData\DaemonEye\logs" -Force -``` - -**Manual Installation**: - -```powershell -# Download from GitHub releases -# https://github.com/EvilBit-Labs/DaemonEye/releases -# Extract to C:\Program Files\DaemonEye\ - -# Add to PATH (run as Administrator) -[Environment]::SetEnvironmentVariable("PATH", "$env:PATH;C:\Program Files\DaemonEye", [EnvironmentVariableTarget]::Machine) - -# Create data directories -New-Item -ItemType Directory -Path "C:\ProgramData\DaemonEye" -Force -New-Item -ItemType Directory -Path "C:\ProgramData\DaemonEye\data" -Force -New-Item -ItemType Directory -Path "C:\ProgramData\DaemonEye\logs" -Force -``` - -## Service Configuration - -### Linux (systemd) - -**Create Service File**: - -```bash -sudo tee /etc/systemd/system/daemoneye.service << 'EOF' -[Unit] -Description=DaemonEye Security Monitoring Agent -Documentation=https://docs.daemoneye.com -After=network.target -Wants=network.target - -[Service] -Type=notify -User=daemoneye -Group=daemoneye -ExecStart=/usr/local/bin/daemoneye-agent --config /etc/daemoneye/config.yaml -ExecReload=/bin/kill -HUP $MAINPID -KillMode=mixed -KillSignal=SIGTERM -TimeoutStopSec=30 -Restart=on-failure -RestartSec=5 -StandardOutput=journal -StandardError=journal -SyslogIdentifier=daemoneye - -# Security settings -NoNewPrivileges=true -PrivateTmp=true -ProtectSystem=strict -ProtectHome=true -ReadWritePaths=/var/lib/daemoneye /var/log/daemoneye -CapabilityBoundingSet=CAP_SYS_PTRACE -AmbientCapabilities=CAP_SYS_PTRACE - -[Install] -WantedBy=multi-user.target -EOF -``` - -**Create User and Directories**: - -```bash -# Create daemoneye user -sudo useradd -r -s /bin/false -d /var/lib/daemoneye daemoneye - -# Set ownership -sudo chown -R daemoneye:daemoneye /var/lib/daemoneye -sudo chown -R daemoneye:daemoneye /var/log/daemoneye -sudo chown -R daemoneye:daemoneye /etc/daemoneye - -# Reload systemd and start service -sudo systemctl daemon-reload -sudo systemctl enable daemoneye -sudo systemctl start daemoneye -``` - -### macOS (launchd) - -**Create LaunchDaemon**: - -```bash -sudo tee /Library/LaunchDaemons/com.daemoneye.agent.plist << 'EOF' - - - - - Label - com.daemoneye.agent - ProgramArguments - - /usr/local/bin/daemoneye-agent - --config - /Library/Application Support/DaemonEye/config.yaml - - RunAtLoad - - KeepAlive - - StandardOutPath - /var/log/daemoneye/agent.log - StandardErrorPath - /var/log/daemoneye/agent.error.log - UserName - daemoneye - GroupName - staff - - -EOF -``` - -**Load and Start Service**: - -```bash -# Load service -sudo launchctl load /Library/LaunchDaemons/com.daemoneye.agent.plist - -# Check status -sudo launchctl list | grep daemoneye -``` - -### Windows (Service) - -**Create Service**: - -```powershell -# Create service -New-Service -Name "DaemonEye Agent" -BinaryPathName "C:\Program Files\DaemonEye\daemoneye-agent.exe --config C:\ProgramData\DaemonEye\config.yaml" -DisplayName "DaemonEye Security Monitoring Agent" -StartupType Automatic - -# Start service -Start-Service "DaemonEye Agent" - -# Check status -Get-Service "DaemonEye Agent" -``` - -## Post-Installation Setup - -### Generate Initial Configuration - -```bash -# Generate default configuration -daemoneye-cli config init --output /etc/daemoneye/config.yaml - -# Or for user-specific configuration -daemoneye-cli config init --output ~/.config/daemoneye/config.yaml -``` - -### Create Data Directories - -```bash -# Linux/macOS -sudo mkdir -p /var/lib/daemoneye -sudo mkdir -p /var/log/daemoneye -sudo chown -R $USER:$USER /var/lib/daemoneye -sudo chown -R $USER:$USER /var/log/daemoneye - -# Windows -mkdir "C:\ProgramData\DaemonEye\data" -mkdir "C:\ProgramData\DaemonEye\logs" -``` - -### Set Up Basic Rules - -```bash -# Create rules directory -mkdir -p /etc/daemoneye/rules - -# Create a basic rule -cat > /etc/daemoneye/rules/suspicious-processes.sql << 'EOF' --- 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; -EOF - -# Validate the rule -daemoneye-cli rules validate /etc/daemoneye/rules/suspicious-processes.sql -``` - -### Configure Alerting - -```bash -# Enable syslog alerts -daemoneye-cli config set alerting.sinks[0].enabled true -daemoneye-cli config set alerting.sinks[0].type syslog -daemoneye-cli config set alerting.sinks[0].facility daemon - -# Enable webhook alerts (if SIEM is available) -daemoneye-cli config set alerting.sinks[1].enabled true -daemoneye-cli config set alerting.sinks[1].type webhook -daemoneye-cli config set alerting.sinks[1].url "https://your-siem.com/webhook" -daemoneye-cli config set alerting.sinks[1].headers.Authorization "Bearer ${WEBHOOK_TOKEN}" -``` - -## Verification - -### Check Installation - -```bash -# Check binary versions -procmond --version -daemoneye-agent --version -daemoneye-cli --version - -# Check service status -# Linux -sudo systemctl status daemoneye - -# macOS -sudo launchctl list | grep daemoneye - -# Windows -Get-Service "DaemonEye Agent" -``` - -### Test Basic Functionality - -```bash -# Check system health -daemoneye-cli health - -# List recent processes -daemoneye-cli query "SELECT pid, name, executable_path FROM processes LIMIT 10" - -# Check alerts -daemoneye-cli alerts list - -# Test rule execution -daemoneye-cli rules test suspicious-processes -``` - -### Performance Verification - -```bash -# Check system metrics -daemoneye-cli metrics - -# Monitor process collection -daemoneye-cli watch processes --filter "cpu_usage > 10.0" - -# Check database status -daemoneye-cli database status -``` - -## Troubleshooting - -### Common Installation Issues - -**Permission Denied**: - -```bash -# Check file permissions -ls -la /usr/local/bin/procmond -ls -la /usr/local/bin/daemoneye-agent -ls -la /usr/local/bin/daemoneye-cli - -# Fix permissions -sudo chmod +x /usr/local/bin/procmond /usr/local/bin/daemoneye-agent /usr/local/bin/daemoneye-cli -``` - -**Service Won't Start**: - -```bash -# Check service logs -# Linux -sudo journalctl -u daemoneye -f - -# macOS -sudo log show --predicate 'process == "daemoneye-agent"' --last 1h - -# Windows -Get-EventLog -LogName Application -Source "DaemonEye" -Newest 10 -``` - -**Configuration Errors**: - -```bash -# Validate configuration -daemoneye-cli config validate - -# Check configuration syntax -daemoneye-cli config check - -# Show effective configuration -daemoneye-cli config show --include-defaults -``` - -**Database Issues**: - -```bash -# Check database status -daemoneye-cli database status - -# Check database integrity -daemoneye-cli database integrity-check - -# Repair database -daemoneye-cli database repair -``` - -### Debug Mode - -```bash -# Enable debug logging -daemoneye-cli config set app.log_level debug - -# Restart service -# Linux -sudo systemctl restart daemoneye - -# macOS -sudo launchctl unload /Library/LaunchDaemons/com.daemoneye.agent.plist -sudo launchctl load /Library/LaunchDaemons/com.daemoneye.agent.plist - -# Windows -Restart-Service "DaemonEye Agent" - -# Monitor debug logs -daemoneye-cli logs --level debug --tail 100 -``` - -### Performance Issues - -**High CPU Usage**: - -```bash -# Check process collection rate -daemoneye-cli metrics --metric collection_rate - -# Reduce scan interval -daemoneye-cli config set app.scan_interval_ms 60000 - -# Check for problematic rules -daemoneye-cli rules list --performance -``` - -**High Memory Usage**: - -```bash -# Check memory usage -daemoneye-cli metrics --metric memory_usage - -# Reduce batch size -daemoneye-cli config set app.batch_size 500 - -# Check database size -daemoneye-cli database size -``` - -**Slow Queries**: - -```bash -# Check query performance -daemoneye-cli database query-stats - -# Optimize database -daemoneye-cli database optimize - -# Check for slow rules -daemoneye-cli rules list --slow -``` - -### 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 -- **Support**: Contact support for commercial assistance - ---- - -*This installation guide provides comprehensive instructions for installing DaemonEye across different platforms. For additional help, consult the troubleshooting section or contact support.* diff --git a/docs/src/deployment/kubernetes.md b/docs/src/deployment/kubernetes.md deleted file mode 100644 index 81b73e78..00000000 --- a/docs/src/deployment/kubernetes.md +++ /dev/null @@ -1,1351 +0,0 @@ -# DaemonEye Kubernetes Deployment Guide - -This guide provides comprehensive instructions for deploying DaemonEye on Kubernetes, including manifests, Helm charts, and production deployment strategies. - ---- - -## Table of Contents - -[TOC] - ---- - -## Kubernetes Overview - -DaemonEye is designed to run efficiently on Kubernetes, providing: - -- **Scalability**: Horizontal pod autoscaling and cluster-wide deployment -- **High Availability**: Multi-replica deployments with health checks -- **Security**: RBAC, network policies, and pod security standards -- **Observability**: Prometheus metrics, structured logging, and distributed tracing -- **Management**: Helm charts and GitOps integration - -### Architecture Components - -- **procmond**: DaemonSet for process monitoring on each node -- **daemoneye-agent**: Deployment for alerting and orchestration -- **daemoneye-cli**: Job/CronJob for management tasks - -## Prerequisites - -### Cluster Requirements - -**Minimum Requirements**: - -- Kubernetes 1.20+ -- 2+ worker nodes -- 4+ CPU cores total -- 8+ GB RAM total -- 50+ GB storage - -**Recommended Requirements**: - -- Kubernetes 1.24+ -- 3+ worker nodes -- 8+ CPU cores total -- 16+ GB RAM total -- 100+ GB storage - -### Required Tools - -```bash -# Install kubectl -curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" -sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl - -# Install Helm -curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash - -# Install kustomize -curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash -``` - -## Basic Deployment - -### Namespace and RBAC - -**namespace.yaml**: - -```yaml -apiVersion: v1 -kind: Namespace -metadata: - name: daemoneye - labels: - name: daemoneye - app.kubernetes.io/name: daemoneye - app.kubernetes.io/version: 1.0.0 -``` - -**rbac.yaml**: - -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: daemoneye-procmond - namespace: daemoneye ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: daemoneye-agent - namespace: daemoneye ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: daemoneye-procmond -rules: -- apiGroups: [""] - resources: ["nodes", "pods"] - verbs: ["get", "list", "watch"] -- apiGroups: [""] - resources: ["pods/exec"] - verbs: ["create"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: daemoneye-procmond -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: daemoneye-procmond -subjects: -- kind: ServiceAccount - name: daemoneye-procmond - namespace: daemoneye -``` - -### ConfigMap and Secrets - -**configmap.yaml**: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: daemoneye-config - namespace: daemoneye -data: - procmond.yaml: | - app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - data_dir: /data - log_dir: /logs - database: - path: /data/processes.db - retention_days: 30 - security: - enable_privilege_dropping: true - drop_to_user: 1000 - drop_to_group: 1000 - - daemoneye-agent.yaml: | - app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - data_dir: /data - log_dir: /logs - database: - path: /data/processes.db - retention_days: 30 - alerting: - enabled: true - sinks: - - type: syslog - enabled: true - facility: daemon - - type: webhook - enabled: true - url: http://daemoneye-webhook:8080/webhook -``` - -**secret.yaml**: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: daemoneye-secrets - namespace: daemoneye -type: Opaque -data: - webhook-token: - database-encryption-key: -``` - -### Persistent Storage - -**pvc.yaml**: - -```yaml -apiVersion: v1 -kind: PersistentVolumeClaim -metadata: - name: daemoneye-data - namespace: daemoneye -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi - storageClassName: fast-ssd -``` - -### DaemonSet for procmond - -**procmond-daemonset.yaml**: - -```yaml -apiVersion: apps/v1 -kind: DaemonSet -metadata: - name: daemoneye-procmond - namespace: daemoneye -spec: - selector: - matchLabels: - app: daemoneye-procmond - template: - metadata: - labels: - app: daemoneye-procmond - spec: - serviceAccountName: daemoneye-procmond - containers: - - name: procmond - image: daemoneye/procmond:1.0.0 - imagePullPolicy: IfNotPresent - securityContext: - privileged: true - runAsUser: 1000 - runAsGroup: 1000 - volumeMounts: - - name: config - mountPath: /config - readOnly: true - - name: data - mountPath: /data - - name: logs - mountPath: /logs - env: - - name: DaemonEye_LOG_LEVEL - value: info - - name: DaemonEye_DATA_DIR - value: /data - - name: DaemonEye_LOG_DIR - value: /logs - command: [procmond] - args: [--config, /config/procmond.yaml] - resources: - requests: - memory: 256Mi - cpu: 100m - limits: - memory: 512Mi - cpu: 500m - livenessProbe: - exec: - command: - - procmond - - health - initialDelaySeconds: 30 - periodSeconds: 30 - timeoutSeconds: 10 - failureThreshold: 3 - readinessProbe: - exec: - command: - - procmond - - health - initialDelaySeconds: 10 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 3 - volumes: - - name: config - configMap: - name: daemoneye-config - - name: data - persistentVolumeClaim: - claimName: daemoneye-data - - name: logs - emptyDir: {} - tolerations: - - key: node-role.kubernetes.io/master - operator: Exists - effect: NoSchedule - - key: node-role.kubernetes.io/control-plane - operator: Exists - effect: NoSchedule -``` - -### Deployment for daemoneye-agent - -**daemoneye-agent-deployment.yaml**: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: daemoneye-agent - namespace: daemoneye -spec: - replicas: 1 - selector: - matchLabels: - app: daemoneye-agent - template: - metadata: - labels: - app: daemoneye-agent - spec: - serviceAccountName: daemoneye-agent - containers: - - name: daemoneye-agent - image: daemoneye/daemoneye-agent:1.0.0 - imagePullPolicy: IfNotPresent - securityContext: - runAsUser: 1000 - runAsGroup: 1000 - volumeMounts: - - name: config - mountPath: /config - readOnly: true - - name: data - mountPath: /data - - name: logs - mountPath: /logs - env: - - name: DaemonEye_LOG_LEVEL - value: info - - name: DaemonEye_DATA_DIR - value: /data - - name: DaemonEye_LOG_DIR - value: /logs - - name: DaemonEye_PROCMOND_ENDPOINT - value: tcp://daemoneye-procmond:8080 - command: [daemoneye-agent] - args: [--config, /config/daemoneye-agent.yaml] - resources: - requests: - memory: 512Mi - cpu: 200m - limits: - memory: 1Gi - cpu: 1000m - livenessProbe: - exec: - command: - - daemoneye-agent - - health - initialDelaySeconds: 30 - periodSeconds: 30 - timeoutSeconds: 10 - failureThreshold: 3 - readinessProbe: - exec: - command: - - daemoneye-agent - - health - initialDelaySeconds: 10 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 3 - volumes: - - name: config - configMap: - name: daemoneye-config - - name: data - persistentVolumeClaim: - claimName: daemoneye-data - - name: logs - emptyDir: {} -``` - -### Service - -**service.yaml**: - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: daemoneye-agent - namespace: daemoneye -spec: - selector: - app: daemoneye-agent - ports: - - name: http - port: 8080 - targetPort: 8080 - protocol: TCP - type: ClusterIP -``` - -### Deploy Basic Setup - -```bash -# Create namespace -kubectl apply -f namespace.yaml - -# Apply RBAC -kubectl apply -f rbac.yaml - -# Apply configuration -kubectl apply -f configmap.yaml -kubectl apply -f secret.yaml - -# Apply storage -kubectl apply -f pvc.yaml - -# Deploy components -kubectl apply -f procmond-daemonset.yaml -kubectl apply -f daemoneye-agent-deployment.yaml -kubectl apply -f service.yaml - -# Check deployment status -kubectl get pods -n daemoneye -kubectl get services -n daemoneye -``` - -## Production Deployment - -### Production Configuration - -**production-configmap.yaml**: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: daemoneye-config - namespace: daemoneye -data: - procmond.yaml: | - app: - scan_interval_ms: 60000 - batch_size: 1000 - log_level: info - data_dir: /data - log_dir: /logs - max_memory_mb: 512 - max_cpu_percent: 5.0 - database: - path: /data/processes.db - retention_days: 30 - max_connections: 20 - cache_size: -128000 - wal_mode: true - security: - enable_privilege_dropping: true - drop_to_user: 1000 - drop_to_group: 1000 - enable_audit_logging: true - audit_log_path: /logs/audit.log - - daemoneye-agent.yaml: | - app: - scan_interval_ms: 60000 - batch_size: 1000 - log_level: info - data_dir: /data - log_dir: /logs - max_memory_mb: 1024 - max_cpu_percent: 10.0 - database: - path: /data/processes.db - retention_days: 30 - max_connections: 20 - cache_size: -128000 - wal_mode: true - alerting: - enabled: true - max_queue_size: 10000 - delivery_timeout_ms: 5000 - retry_attempts: 3 - sinks: - - type: syslog - enabled: true - facility: daemon - priority: info - - type: webhook - enabled: true - url: http://daemoneye-webhook:8080/webhook - timeout_ms: 5000 - retry_attempts: 3 - - type: file - enabled: true - path: /logs/alerts.log - format: json - rotation: daily - max_files: 30 - detection: - enable_detection: true - rule_directory: /rules - enable_hot_reload: true - max_concurrent_rules: 10 - rule_timeout_ms: 30000 - enable_rule_caching: true - cache_ttl_seconds: 300 - observability: - enable_metrics: true - metrics_port: 9090 - metrics_path: /metrics - enable_health_checks: true - health_check_port: 8080 - health_check_path: /health - logging: - enable_structured_logging: true - log_format: json - enable_log_rotation: true - max_log_file_size_mb: 100 - max_log_files: 10 -``` - -### Production DaemonSet - -**production-procmond-daemonset.yaml**: - -```yaml -apiVersion: apps/v1 -kind: DaemonSet -metadata: - name: daemoneye-procmond - namespace: daemoneye -spec: - selector: - matchLabels: - app: daemoneye-procmond - template: - metadata: - labels: - app: daemoneye-procmond - annotations: - prometheus.io/scrape: 'true' - prometheus.io/port: '9090' - prometheus.io/path: /metrics - spec: - serviceAccountName: daemoneye-procmond - securityContext: - runAsUser: 1000 - runAsGroup: 1000 - fsGroup: 1000 - containers: - - name: procmond - image: daemoneye/procmond:1.0.0 - imagePullPolicy: IfNotPresent - securityContext: - privileged: true - allowPrivilegeEscalation: false - readOnlyRootFilesystem: true - runAsUser: 1000 - runAsGroup: 1000 - capabilities: - add: - - CAP_SYS_PTRACE - - CAP_SYS_ADMIN - drop: - - ALL - volumeMounts: - - name: config - mountPath: /config - readOnly: true - - name: data - mountPath: /data - - name: logs - mountPath: /logs - - name: rules - mountPath: /rules - readOnly: true - - name: tmp - mountPath: /tmp - env: - - name: DaemonEye_LOG_LEVEL - value: info - - name: DaemonEye_DATA_DIR - value: /data - - name: DaemonEye_LOG_DIR - value: /logs - - name: DaemonEye_RULE_DIR - value: /rules - command: [procmond] - args: [--config, /config/procmond.yaml] - resources: - requests: - memory: 256Mi - cpu: 100m - limits: - memory: 512Mi - cpu: 500m - livenessProbe: - exec: - command: - - procmond - - health - initialDelaySeconds: 30 - periodSeconds: 30 - timeoutSeconds: 10 - failureThreshold: 3 - readinessProbe: - exec: - command: - - procmond - - health - initialDelaySeconds: 10 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 3 - ports: - - name: metrics - containerPort: 9090 - protocol: TCP - - name: health - containerPort: 8080 - protocol: TCP - volumes: - - name: config - configMap: - name: daemoneye-config - - name: data - persistentVolumeClaim: - claimName: daemoneye-data - - name: logs - emptyDir: {} - - name: rules - configMap: - name: daemoneye-rules - - name: tmp - emptyDir: {} - tolerations: - - key: node-role.kubernetes.io/master - operator: Exists - effect: NoSchedule - - key: node-role.kubernetes.io/control-plane - operator: Exists - effect: NoSchedule - - key: node.kubernetes.io/not-ready - operator: Exists - effect: NoExecute - tolerationSeconds: 300 - - key: node.kubernetes.io/unreachable - operator: Exists - effect: NoExecute - tolerationSeconds: 300 - nodeSelector: - kubernetes.io/os: linux - affinity: - nodeAffinity: - requiredDuringSchedulingIgnoredDuringExecution: - nodeSelectorTerms: - - matchExpressions: - - key: kubernetes.io/arch - operator: In - values: - - amd64 - - arm64 -``` - -### Production Deployment - -**production-daemoneye-agent-deployment.yaml**: - -```yaml -apiVersion: apps/v1 -kind: Deployment -metadata: - name: daemoneye-agent - namespace: daemoneye -spec: - replicas: 2 - selector: - matchLabels: - app: daemoneye-agent - template: - metadata: - labels: - app: daemoneye-agent - annotations: - prometheus.io/scrape: 'true' - prometheus.io/port: '9090' - prometheus.io/path: /metrics - spec: - serviceAccountName: daemoneye-agent - securityContext: - runAsUser: 1000 - runAsGroup: 1000 - fsGroup: 1000 - containers: - - name: daemoneye-agent - image: daemoneye/daemoneye-agent:1.0.0 - imagePullPolicy: IfNotPresent - securityContext: - allowPrivilegeEscalation: false - readOnlyRootFilesystem: true - runAsUser: 1000 - runAsGroup: 1000 - capabilities: - drop: - - ALL - volumeMounts: - - name: config - mountPath: /config - readOnly: true - - name: data - mountPath: /data - - name: logs - mountPath: /logs - - name: tmp - mountPath: /tmp - env: - - name: DaemonEye_LOG_LEVEL - value: info - - name: DaemonEye_DATA_DIR - value: /data - - name: DaemonEye_LOG_DIR - value: /logs - - name: DaemonEye_PROCMOND_ENDPOINT - value: tcp://daemoneye-procmond:8080 - command: [daemoneye-agent] - args: [--config, /config/daemoneye-agent.yaml] - resources: - requests: - memory: 512Mi - cpu: 200m - limits: - memory: 1Gi - cpu: 1000m - livenessProbe: - exec: - command: - - daemoneye-agent - - health - initialDelaySeconds: 30 - periodSeconds: 30 - timeoutSeconds: 10 - failureThreshold: 3 - readinessProbe: - exec: - command: - - daemoneye-agent - - health - initialDelaySeconds: 10 - periodSeconds: 10 - timeoutSeconds: 5 - failureThreshold: 3 - ports: - - name: metrics - containerPort: 9090 - protocol: TCP - - name: health - containerPort: 8080 - protocol: TCP - volumes: - - name: config - configMap: - name: daemoneye-config - - name: data - persistentVolumeClaim: - claimName: daemoneye-data - - name: logs - emptyDir: {} - - name: tmp - emptyDir: {} - affinity: - podAntiAffinity: - preferredDuringSchedulingIgnoredDuringExecution: - - weight: 100 - podAffinityTerm: - labelSelector: - matchExpressions: - - key: app - operator: In - values: - - daemoneye-agent - topologyKey: kubernetes.io/hostname -``` - -### Horizontal Pod Autoscaler - -**hpa.yaml**: - -```yaml -apiVersion: autoscaling/v2 -kind: HorizontalPodAutoscaler -metadata: - name: daemoneye-agent-hpa - namespace: daemoneye -spec: - scaleTargetRef: - apiVersion: apps/v1 - kind: Deployment - name: daemoneye-agent - minReplicas: 2 - maxReplicas: 10 - metrics: - - type: Resource - resource: - name: cpu - target: - type: Utilization - averageUtilization: 70 - - type: Resource - resource: - name: memory - target: - type: Utilization - averageUtilization: 80 - behavior: - scaleDown: - stabilizationWindowSeconds: 300 - policies: - - type: Percent - value: 10 - periodSeconds: 60 - scaleUp: - stabilizationWindowSeconds: 60 - policies: - - type: Percent - value: 50 - periodSeconds: 60 -``` - -## Helm Chart Deployment - -### Helm Chart Structure - -``` -daemoneye/ -├── Chart.yaml -├── values.yaml -├── values-production.yaml -├── values-development.yaml -├── templates/ -│ ├── namespace.yaml -│ ├── rbac.yaml -│ ├── configmap.yaml -│ ├── secret.yaml -│ ├── pvc.yaml -│ ├── procmond-daemonset.yaml -│ ├── daemoneye-agent-deployment.yaml -│ ├── service.yaml -│ ├── hpa.yaml -│ ├── networkpolicy.yaml -│ └── servicemonitor.yaml -└── charts/ -``` - -### Chart.yaml - -```yaml -apiVersion: v2 -name: daemoneye -description: DaemonEye Security Monitoring Agent -type: application -version: 1.0.0 -appVersion: 1.0.0 -keywords: - - security - - monitoring - - processes - - threat-detection -home: https://daemoneye.com -sources: - - https://github.com/daemoneye/daemoneye -maintainers: - - name: DaemonEye Team - email: team@daemoneye.com -dependencies: - - name: prometheus - version: 15.0.0 - repository: https://prometheus-community.github.io/helm-charts - condition: monitoring.prometheus.enabled -``` - -### values.yaml - -```yaml -# Default values for daemoneye -image: - repository: daemoneye - tag: 1.0.0 - pullPolicy: IfNotPresent - -replicaCount: 1 - -serviceAccount: - create: true - annotations: {} - name: '' - -podSecurityContext: - runAsUser: 1000 - runAsGroup: 1000 - fsGroup: 1000 - -securityContext: - allowPrivilegeEscalation: false - capabilities: - drop: - - ALL - readOnlyRootFilesystem: true - runAsNonRoot: true - runAsUser: 1000 - -service: - type: ClusterIP - port: 8080 - -ingress: - enabled: false - className: '' - annotations: {} - hosts: - - host: daemoneye.example.com - paths: - - path: / - pathType: Prefix - tls: [] - -resources: - limits: - cpu: 1000m - memory: 1Gi - requests: - cpu: 200m - memory: 512Mi - -autoscaling: - enabled: false - minReplicas: 1 - maxReplicas: 10 - targetCPUUtilizationPercentage: 80 - targetMemoryUtilizationPercentage: 80 - -nodeSelector: {} - -tolerations: [] - -affinity: {} - -persistence: - enabled: true - storageClass: '' - accessMode: ReadWriteOnce - size: 10Gi - -config: - app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - database: - retention_days: 30 - alerting: - enabled: true - sinks: - - type: syslog - enabled: true - facility: daemon - -secrets: {} - -monitoring: - enabled: false - serviceMonitor: - enabled: false - namespace: '' - interval: 30s - scrapeTimeout: 10s - prometheus: - enabled: false - server: - enabled: true - persistentVolume: - enabled: true - size: 8Gi - alertmanager: - enabled: true - persistentVolume: - enabled: true - size: 2Gi - grafana: - enabled: false - adminPassword: admin - persistentVolume: - enabled: true - size: 1Gi - -networkPolicy: - enabled: false - ingress: - enabled: true - rules: [] - egress: - enabled: true - rules: [] -``` - -### Deploy with Helm - -```bash -# Add DaemonEye Helm repository -helm repo add daemoneye https://charts.daemoneye.com -helm repo update - -# Install DaemonEye -helm install daemoneye daemoneye/daemoneye \ - --namespace daemoneye \ - --create-namespace \ - --values values.yaml - -# Install with production values -helm install daemoneye daemoneye/daemoneye \ - --namespace daemoneye \ - --create-namespace \ - --values values-production.yaml - -# Upgrade deployment -helm upgrade daemoneye daemoneye/daemoneye \ - --namespace daemoneye \ - --values values.yaml - -# Uninstall -helm uninstall daemoneye --namespace daemoneye -``` - -## Security Configuration - -### Network Policies - -**networkpolicy.yaml**: - -```yaml -apiVersion: networking.k8s.io/v1 -kind: NetworkPolicy -metadata: - name: daemoneye-network-policy - namespace: daemoneye -spec: - podSelector: - matchLabels: - app: daemoneye - policyTypes: - - Ingress - - Egress - ingress: - - from: - - namespaceSelector: - matchLabels: - name: daemoneye - - podSelector: - matchLabels: - app: daemoneye - ports: - - protocol: TCP - port: 8080 - - protocol: TCP - port: 9090 - egress: - - to: - - namespaceSelector: - matchLabels: - name: daemoneye - - podSelector: - matchLabels: - app: daemoneye - ports: - - protocol: TCP - port: 8080 - - protocol: TCP - port: 9090 - - to: [] - ports: - - protocol: TCP - port: 53 - - protocol: UDP - port: 53 -``` - -### Pod Security Standards - -**pod-security-policy.yaml**: - -```yaml -apiVersion: policy/v1beta1 -kind: PodSecurityPolicy -metadata: - name: daemoneye-psp -spec: - privileged: false - allowPrivilegeEscalation: false - requiredDropCapabilities: - - ALL - volumes: - - configMap - - emptyDir - - projected - - secret - - downwardAPI - - persistentVolumeClaim - runAsUser: - rule: MustRunAsNonRoot - seLinux: - rule: RunAsAny - fsGroup: - rule: RunAsAny -``` - -### RBAC Configuration - -**rbac.yaml**: - -```yaml -apiVersion: v1 -kind: ServiceAccount -metadata: - name: daemoneye-procmond - namespace: daemoneye ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: daemoneye-agent - namespace: daemoneye ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: daemoneye-procmond -rules: -- apiGroups: [""] - resources: ["nodes", "pods"] - verbs: ["get", "list", "watch"] -- apiGroups: [""] - resources: ["pods/exec"] - verbs: ["create"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: daemoneye-procmond -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: daemoneye-procmond -subjects: -- kind: ServiceAccount - name: daemoneye-procmond - namespace: daemoneye ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: daemoneye-agent -rules: -- apiGroups: [""] - resources: ["pods", "services", "endpoints"] - verbs: ["get", "list", "watch"] ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: daemoneye-agent -roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: daemoneye-agent -subjects: -- kind: ServiceAccount - name: daemoneye-agent - namespace: daemoneye -``` - -## Monitoring and Observability - -### Prometheus ServiceMonitor - -**servicemonitor.yaml**: - -```yaml -apiVersion: monitoring.coreos.com/v1 -kind: ServiceMonitor -metadata: - name: daemoneye - namespace: daemoneye - labels: - app: daemoneye -spec: - selector: - matchLabels: - app: daemoneye - endpoints: - - port: metrics - path: /metrics - interval: 30s - scrapeTimeout: 10s -``` - -### Grafana Dashboard - -**grafana-dashboard.yaml**: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: daemoneye-grafana-dashboard - namespace: daemoneye - labels: - grafana_dashboard: '1' -data: - daemoneye-dashboard.json: | - { - "dashboard": { - "title": "DaemonEye Monitoring", - "panels": [ - { - "title": "Process Collection Rate", - "type": "graph", - "targets": [ - { - "expr": "rate(daemoneye_processes_collected_total[5m])", - "legendFormat": "Processes/sec" - } - ] - }, - { - "title": "Memory Usage", - "type": "graph", - "targets": [ - { - "expr": "daemoneye_memory_usage_bytes", - "legendFormat": "Memory Usage" - } - ] - } - ] - } - } -``` - -## Troubleshooting - -### Common Issues - -**Pod Won't Start**: - -```bash -# Check pod status -kubectl get pods -n daemoneye - -# Check pod logs -kubectl logs -n daemoneye daemoneye-procmond-xxx - -# Check pod events -kubectl describe pod -n daemoneye daemoneye-procmond-xxx -``` - -**Permission Denied**: - -```bash -# Check security context -kubectl get pod -n daemoneye daemoneye-procmond-xxx -o yaml | grep securityContext - -# Check file permissions -kubectl exec -n daemoneye daemoneye-procmond-xxx -- ls -la /data -``` - -**Network Issues**: - -```bash -# Check service endpoints -kubectl get endpoints -n daemoneye - -# Check network connectivity -kubectl exec -n daemoneye daemoneye-agent-xxx -- ping daemoneye-procmond -``` - -**Database Issues**: - -```bash -# Check database status -kubectl exec -n daemoneye daemoneye-agent-xxx -- daemoneye-cli database status - -# Check database integrity -kubectl exec -n daemoneye daemoneye-agent-xxx -- daemoneye-cli database integrity-check -``` - -### Debug Mode - -**Enable Debug Logging**: - -```yaml -# Update ConfigMap -apiVersion: v1 -kind: ConfigMap -metadata: - name: daemoneye-config - namespace: daemoneye -data: - procmond.yaml: | - app: - log_level: debug - # ... rest of config -``` - -**Debug Pod**: - -```bash -# Run debug pod -kubectl run debug --image=daemoneye/daemoneye-cli:1.0.0 -it --rm -- /bin/sh - -# Check system capabilities -kubectl run debug --image=daemoneye/daemoneye-cli:1.0.0 -it --rm -- capsh --print -``` - -### Performance Issues - -**High CPU Usage**: - -```bash -# Check resource usage -kubectl top pods -n daemoneye - -# Check HPA status -kubectl get hpa -n daemoneye - -# Scale up manually -kubectl scale deployment daemoneye-agent --replicas=3 -n daemoneye -``` - -**High Memory Usage**: - -```bash -# Check memory usage -kubectl top pods -n daemoneye - -# Check memory limits -kubectl describe pod -n daemoneye daemoneye-agent-xxx | grep Limits -``` - -**Slow Database Operations**: - -```bash -# Check database performance -kubectl exec -n daemoneye daemoneye-agent-xxx -- daemoneye-cli database query-stats - -# Optimize database -kubectl exec -n daemoneye daemoneye-agent-xxx -- daemoneye-cli database optimize -``` - ---- - -*This Kubernetes deployment guide provides comprehensive instructions for deploying DaemonEye on Kubernetes. For additional help, consult the troubleshooting section or contact support.* diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index 0f7f0b32..b4c72308 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -522,13 +522,14 @@ daemoneye-agent --config /etc/daemoneye/config.yaml --log-level debug ## Next Steps -Now that you have DaemonEye running: +Now that you understand the prerequisites and architecture: -1. **Read the [Operator Guide](../user-guides/operator-guide.md)** for detailed usage instructions -2. **Explore [Configuration Guide](../user-guides/configuration.md)** for advanced configuration -3. **Learn [Rule Development](../user-guides/rule-development.md)** for creating custom detection rules -4. **Review [Security Architecture](../architecture/security-model.md)** for understanding the security model -5. **Check [Deployment Guide](../deployment/installation.md)** for production deployment +1. **Review the [Architecture](./architecture.md)** for the system overview +2. **Read the [Technical Documentation](./technical.md)** for implementation details +3. **Consult the [Security](./security.md) section** for the threat model and security boundaries +4. **See [Contributing](./contributing.md)** 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 diff --git a/docs/src/introduction.md b/docs/src/introduction.md index d748c0e7..dd42c743 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,31 +1,33 @@ # DaemonEye Documentation -Welcome to the DaemonEye documentation! This comprehensive guide covers everything you need to know about DaemonEye, a high-performance, security-focused process monitoring system built in Rust. +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 a complete rewrite of the Python prototype, designed for cybersecurity professionals, threat hunters, and security operations centers. It provides real-time process monitoring, threat detection, and alerting capabilities across multiple platforms. +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 -- **Threat Detection**: SQL-based detection rules with hot-reloading capabilities -- **Multi-tier Architecture**: Core, Business, and Enterprise tiers with different feature sets -- **Cross-platform Support**: Linux, macOS, and Windows support -- **Container Ready**: Docker and Kubernetes deployment options -- **Security Focused**: Built with security best practices and minimal attack surface +- **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; Ed25519-signed events +- **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 tiers (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 robust three-component security architecture: +DaemonEye follows a three-component security architecture: -1. **procmond (Collector)**: Privileged process monitoring daemon built on collector-core framework with minimal attack surface +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 database queries and system management +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. @@ -33,40 +35,30 @@ This separation ensures robust security by isolating privileged operations from This documentation is organized into several sections: -- **[Getting Started](./getting-started.md)**: Quick start guide for new users -- **[Project Overview](./project-overview.md)**: Detailed project information and features +- **[Getting Started](./getting-started.md)**: Prerequisites, privilege model, and architectural orientation +- **[Project Overview](./project-overview.md)**: Detailed project information and value propositions - **[Architecture](./architecture.md)**: System architecture and design principles - **[Technical Documentation](./technical.md)**: Technical specifications and implementation details -- **[User Guides](./user-guides.md)**: Comprehensive user and operator guides -- **[API Reference](./api-reference.md)**: Complete API documentation -- **[Deployment](./deployment.md)**: Installation and deployment guides -- **[Security](./security.md)**: Security considerations and best practices +- **[Security](./security.md)**: Security model and design overview - **[Testing](./testing.md)**: Testing strategies and guidelines - **[Contributing](./contributing.md)**: Contribution guidelines and development setup -## Quick Links - -- [Installation Guide](./deployment/installation.md) -- [Configuration Guide](./user-guides/configuration.md) -- [Operator Guide](./user-guides/operator-guide.md) -- [API Reference](./api-reference/core-api.md) -- [Docker Deployment](./deployment/docker.md) -- [Kubernetes Deployment](./deployment/kubernetes.md) +> **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](./getting-started.md) guide -2. Review the [Troubleshooting](./user-guides/operator-guide.md#troubleshooting) section -3. Consult the [API Reference](./api-reference/core-api.md) for technical details -4. Join our community discussions on GitHub +2. Review the [Architecture](./architecture.md) and [Technical Documentation](./technical.md) +3. Consult the [Security](./security.md) 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 — are licensed under Apache 2.0. Commercial extensions ship separately; see evilbitlabs.io for details. +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 is continuously updated. For the latest information, always refer to the most recent version.* +*This documentation tracks the development state of the DaemonEye Community tier and is updated as the codebase evolves.* diff --git a/docs/src/project-overview.md b/docs/src/project-overview.md index 49df3e7a..e5107760 100644 --- a/docs/src/project-overview.md +++ b/docs/src/project-overview.md @@ -258,10 +258,12 @@ The DaemonEye components in this repository are licensed under Apache 2.0. Comme ### **Next Steps** -- Read the [Architecture Overview](./architecture-overview.md) to understand the system design -- Follow the [Getting Started Guide](./getting-started.md) for detailed setup instructions -- Review the [Operator Guide](../user-guides/operator-guide.md) for day-to-day usage -- Explore the [Configuration Guide](../user-guides/configuration.md) for advanced configuration +- Read the [Architecture Overview](./architecture.md) to understand the system design +- Follow the [Getting Started Guide](./getting-started.md) for prerequisites and orientation +- Review the [Technical Documentation](./technical.md) for implementation specifications +- Consult the [Security](./security.md) section for the threat model and security boundaries + +> **Note:** Operator and configuration guides will be published with the v1.0.0 release. --- diff --git a/docs/src/user-guides.md b/docs/src/user-guides.md deleted file mode 100644 index 850e509c..00000000 --- a/docs/src/user-guides.md +++ /dev/null @@ -1,547 +0,0 @@ -# User Guides - -This section contains comprehensive user guides for DaemonEye, covering everything from basic usage to advanced configuration and troubleshooting. - ---- - -## Table of Contents - -[TOC] - ---- - -## Operator Guide - -The operator guide provides comprehensive information for system administrators and security operators who need to deploy, configure, and maintain DaemonEye in production environments. - -[Read Operator Guide →](./user-guides/operator-guide.md) - -## Configuration Guide - -The configuration guide covers all aspects of DaemonEye configuration, from basic settings to advanced tuning and security hardening. - -[Read Configuration Guide →](./user-guides/configuration.md) - -## Quick Start - -### Installation - -Install DaemonEye using your preferred method: - -**Using Package Managers**: - -```bash -# Ubuntu/Debian -sudo apt install daemoneye - -# RHEL/CentOS -sudo yum install daemoneye - -# macOS -brew install daemoneye - -# Windows -choco install daemoneye -``` - -**Using Docker**: - -```bash -docker run -d --privileged \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - daemoneye/daemoneye:latest -``` - -**Using Kubernetes**: - -```bash -kubectl apply -f https://raw.githubusercontent.com/EvilBit-Labs/daemoneye/main/deploy/kubernetes/daemoneye.yaml -``` - -### Basic Configuration - -Create a basic configuration file: - -```yaml -# /etc/daemoneye/config.yaml -app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - data_dir: /var/lib/daemoneye - log_dir: /var/log/daemoneye - -database: - path: /var/lib/daemoneye/processes.db - retention_days: 30 - -alerting: - enabled: true - sinks: - - type: syslog - enabled: true - facility: daemon -``` - -### Starting DaemonEye - -**Linux (systemd)**: - -```bash -sudo systemctl start daemoneye -sudo systemctl enable daemoneye -``` - -**macOS (launchd)**: - -```bash -sudo launchctl load /Library/LaunchDaemons/com.daemoneye.agent.plist -``` - -**Windows (Service)**: - -```powershell -Start-Service DaemonEye -``` - -**Docker**: - -```bash -docker run -d --name daemoneye \ - --privileged \ - -v /etc/daemoneye:/config:ro \ - -v /var/lib/daemoneye:/data \ - -v /var/log/daemoneye:/logs \ - daemoneye/daemoneye:latest -``` - -### Basic Usage - -**Check Database Status**: - -```bash -# View database statistics in human-readable format -daemoneye-cli --database /var/lib/daemoneye/processes.db --format human - -# View database statistics in JSON format -daemoneye-cli --database /var/lib/daemoneye/processes.db --format json -``` - -**Start Process Collection**: - -```bash -# Start daemoneye-agent (orchestrator) -daemoneye-agent --database /var/lib/daemoneye/processes.db --log-level info - -# Run procmond directly with enhanced collection -procmond --database /var/lib/daemoneye/processes.db --interval 30 --enhanced-metadata --compute-hashes -``` - -**Component Help**: - -```bash -# Get help for each component -daemoneye-agent --help -daemoneye-cli --help -procmond --help -``` - -## Common Tasks - -### Process Monitoring - -**Monitor Specific Processes**: - -```bash -# Monitor processes by name -daemoneye-cli watch processes --filter "name LIKE '%apache%'" - -# Monitor processes by CPU usage -daemoneye-cli watch processes --filter "cpu_usage > 10.0" - -# Monitor processes by memory usage -daemoneye-cli watch processes --filter "memory_usage > 1000000" -``` - -**Query Process Information**: - -```bash -# Get all processes -daemoneye-cli query "SELECT * FROM processes" - -# Get processes by PID -daemoneye-cli query "SELECT * FROM processes WHERE pid = 1234" - -# Get processes by name pattern -daemoneye-cli query "SELECT * FROM processes WHERE name LIKE '%nginx%'" - -# Get processes by executable path -daemoneye-cli query "SELECT * FROM processes WHERE executable_path LIKE '%/usr/bin/%'" -``` - -### Alert Management - -**Configure Alerting**: - -```bash -# Enable syslog alerts -daemoneye-cli config set alerting.sinks[0].enabled true -daemoneye-cli config set alerting.sinks[0].type syslog -daemoneye-cli config set alerting.sinks[0].facility daemon - -# Enable webhook alerts -daemoneye-cli config set alerting.sinks[1].enabled true -daemoneye-cli config set alerting.sinks[1].type webhook -daemoneye-cli config set alerting.sinks[1].url "https://alerts.example.com/webhook" -``` - -**View Alerts**: - -```bash -# List recent alerts -daemoneye-cli alerts list - -# List alerts by severity -daemoneye-cli alerts list --severity high - -# List alerts by rule -daemoneye-cli alerts list --rule "suspicious_processes" - -# Get alert details -daemoneye-cli alerts show -``` - -### Rule Management - -**Create Detection Rules**: - -```bash -# Create a rule file -cat > /etc/daemoneye/rules/suspicious-processes.sql << 'EOF' --- 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; -EOF - -# Validate the rule -daemoneye-cli rules validate /etc/daemoneye/rules/suspicious-processes.sql - -# Test the rule -daemoneye-cli rules test suspicious-processes -``` - -**Manage Rules**: - -```bash -# List all rules -daemoneye-cli rules list - -# Enable/disable rules -daemoneye-cli rules enable suspicious-processes -daemoneye-cli rules disable suspicious-processes - -# Reload rules -daemoneye-cli rules reload -``` - -### Configuration Management - -**View Configuration**: - -```bash -# Show current configuration -daemoneye-cli config show - -# Show specific setting -daemoneye-cli config get app.scan_interval_ms - -# Show all settings with defaults -daemoneye-cli config show --include-defaults -``` - -**Update Configuration**: - -```bash -# Set a single value -daemoneye-cli config set app.scan_interval_ms 60000 - -# Set multiple values -daemoneye-cli config set app.scan_interval_ms 60000 app.batch_size 500 - -# Update from file -daemoneye-cli config load /path/to/config.yaml -``` - -**Validate Configuration**: - -```bash -# Validate configuration -daemoneye-cli config validate - -# Check configuration syntax -daemoneye-cli config check -``` - -## Troubleshooting - -### Common Issues - -**Service Won't Start**: - -```bash -# Check service status -sudo systemctl status daemoneye - -# Check logs -sudo journalctl -u daemoneye -f - -# Check configuration -daemoneye-cli config validate -``` - -**Permission Denied**: - -```bash -# Check file permissions -ls -la /var/lib/daemoneye/ -ls -la /var/log/daemoneye/ - -# Fix permissions -sudo chown -R daemoneye:daemoneye /var/lib/daemoneye -sudo chown -R daemoneye:daemoneye /var/log/daemoneye -``` - -**Database Issues**: - -```bash -# Check database status -daemoneye-cli database status - -# Check database integrity -daemoneye-cli database integrity-check - -# Repair database -daemoneye-cli database repair -``` - -**Performance Issues**: - -```bash -# Check system metrics -daemoneye-cli metrics - -# Check resource usage -daemoneye-cli system status - -# Optimize configuration -daemoneye-cli config optimize -``` - -### Debug Mode - -**Enable Debug Logging**: - -```bash -# Set debug level -daemoneye-cli config set app.log_level debug - -# Restart service -sudo systemctl restart daemoneye - -# Monitor debug logs -daemoneye-cli logs --level debug --tail 100 -``` - -**Debug Specific Components**: - -```bash -# Debug process collection -daemoneye-cli debug collector - -# Debug alert delivery -daemoneye-cli debug alerts - -# Debug database operations -daemoneye-cli debug database -``` - -### Health Checks - -**System Health**: - -```bash -# Overall health -daemoneye-cli health - -# Component health -daemoneye-cli health --component procmond -daemoneye-cli health --component daemoneye-agent -daemoneye-cli health --component database - -# Detailed health report -daemoneye-cli health --verbose -``` - -**Performance Health**: - -```bash -# Performance metrics -daemoneye-cli metrics - -# Resource usage -daemoneye-cli system resources - -# Performance analysis -daemoneye-cli system analyze -``` - -## Advanced Usage - -### Custom Integrations - -**SIEM Integration**: - -```yaml -# Splunk HEC -integrations: - siem: - splunk: - enabled: true - hec_url: https://splunk.example.com:8088/services/collector - hec_token: ${SPLUNK_HEC_TOKEN} - index: daemoneye - -# Elasticsearch -integrations: - siem: - elasticsearch: - enabled: true - url: https://elasticsearch.example.com:9200 - username: ${ELASTIC_USERNAME} - password: ${ELASTIC_PASSWORD} - index: daemoneye-processes -``` - -**Export Formats**: - -```yaml -# CEF Export -integrations: - export: - cef: - enabled: true - output_file: /var/log/daemoneye/cef.log - cef_version: '1.0' - device_vendor: DaemonEye - device_product: Process Monitor - -``` - -Additional export formats (STIX/TAXII and others) are available in commercial tiers. - -### Performance Tuning - -**Optimize for High Load**: - -```yaml -app: - scan_interval_ms: 60000 # Reduce scan frequency - batch_size: 500 # Smaller batches - max_memory_mb: 256 # Limit memory usage - max_cpu_percent: 3.0 # Limit CPU usage - -database: - cache_size: -128000 # 128MB cache - temp_store: MEMORY # Use memory for temp tables - synchronous: NORMAL # Balance safety and performance -``` - -**Optimize for Low Latency**: - -```yaml -app: - scan_interval_ms: 10000 # Increase scan frequency - batch_size: 100 # Smaller batches - max_memory_mb: 512 # More memory for caching - -detection: - enable_rule_caching: true - cache_ttl_seconds: 300 - max_concurrent_rules: 5 -``` - -### Security Hardening - -**Enable Security Features**: - -```yaml -security: - enable_privilege_dropping: true - drop_to_user: daemoneye - drop_to_group: daemoneye - enable_audit_logging: true - enable_integrity_checking: true - hash_algorithm: blake3 - enable_signature_verification: true -``` - -**Network Security**: - -```yaml -security: - network: - enable_tls: true - cert_file: /etc/daemoneye/cert.pem - key_file: /etc/daemoneye/key.pem - ca_file: /etc/daemoneye/ca.pem - verify_peer: true -``` - -## Best Practices - -### Deployment - -1. **Start Small**: Begin with basic monitoring and gradually add features -2. **Test Configuration**: Always validate configuration before deployment -3. **Monitor Resources**: Keep an eye on CPU and memory usage -4. **Regular Updates**: Keep DaemonEye updated with latest releases -5. **Backup Data**: Regularly backup configuration and data - -### Configuration - -1. **Use Hierarchical Config**: Leverage multiple configuration sources -2. **Environment Variables**: Use environment variables for secrets -3. **Validation**: Always validate configuration changes -4. **Documentation**: Document custom configurations -5. **Version Control**: Keep configuration files in version control - -### Monitoring - -1. **Set Up Alerting**: Configure appropriate alert thresholds -2. **Monitor Performance**: Track system performance metrics -3. **Log Analysis**: Regularly review logs for issues -4. **Health Checks**: Implement automated health monitoring -5. **Incident Response**: Have a plan for handling alerts - -### Security - -1. **Principle of Least Privilege**: Run with minimal required privileges -2. **Network Security**: Use TLS for all network communications -3. **Access Control**: Implement proper authentication and authorization -4. **Audit Logging**: Enable comprehensive audit logging -5. **Regular Updates**: Keep security patches current - ---- - -*This user guide provides comprehensive information for using DaemonEye. For additional help, consult the specific user guides or contact support.* diff --git a/docs/src/user-guides/configuration.md b/docs/src/user-guides/configuration.md deleted file mode 100644 index 392c480a..00000000 --- a/docs/src/user-guides/configuration.md +++ /dev/null @@ -1,617 +0,0 @@ -# DaemonEye Configuration Guide - -This guide provides comprehensive information about configuring DaemonEye for different deployment scenarios and requirements. - -## Table of Contents - -- [Configuration Overview](#configuration-overview) -- [Configuration Hierarchy](#configuration-hierarchy) -- [Core Configuration](#core-configuration) -- [Alerting Configuration](#alerting-configuration) -- [Database Configuration](#database-configuration) -- [Platform-Specific Configuration](#platform-specific-configuration) -- [Environment Variables](#environment-variables) -- [Configuration Examples](#configuration-examples) -- [Troubleshooting](#troubleshooting) - -## Configuration Overview - -DaemonEye uses a hierarchical configuration system that allows you to override settings at different levels. The configuration is loaded in the following order (later sources override earlier ones): - -1. **Embedded defaults** (lowest precedence) -2. **System configuration files** (`/etc/daemoneye/config.yaml`) -3. **User configuration files** (`~/.config/daemoneye/config.yaml`) -4. **Environment variables** (`DAEMONEYE_*`) -5. **Command-line flags** (highest precedence) - -## Configuration Hierarchy - -### File Locations - -**System Configuration**: - -- Linux: `/etc/daemoneye/config.yaml` -- macOS: `/Library/Application Support/DaemonEye/config.yaml` -- Windows: `C:\ProgramData\DaemonEye\config.yaml` - -**User Configuration**: - -- Linux/macOS: `~/.config/daemoneye/config.yaml` -- Windows: `%APPDATA%\DaemonEye\config.yaml` - -**Component-Specific Configuration**: - -- Components use the same configuration file with component-specific sections -- Environment variables can override specific component settings -- Command-line flags provide the highest precedence overrides - -### Configuration Formats - -DaemonEye supports multiple configuration formats: - -- **YAML** (recommended): Human-readable, supports comments -- **JSON**: Machine-readable, no comments -- **TOML**: Alternative human-readable format - -## Core Configuration - -### Application Settings - -```yaml -app: - # Scan interval in milliseconds - scan_interval_ms: 30000 - - # Batch size for process collection - batch_size: 1000 - - # Log level: debug, info, warn, error - log_level: info - - # Data retention period in days - retention_days: 30 - - # Maximum memory usage in MB - max_memory_mb: 512 - - # Enable performance monitoring - enable_metrics: true - - # Metrics collection interval in seconds - metrics_interval_secs: 60 - -# EventBus broker configuration (daemoneye-agent) -broker: - # Unix socket path for EventBus broker - socket_path: /tmp/daemoneye-eventbus.sock - - # Broker startup timeout in seconds - startup_timeout_seconds: 30 - - # Maximum message buffer size - max_message_buffer_size: 10000 - - # Message processing timeout in milliseconds - message_timeout_ms: 5000 -``` - -### Process Collection Settings - -```yaml -collection: - # Enable process enumeration - enable_process_collection: true - - # Enable executable hashing - enable_hash_computation: true - - # Hash algorithm (sha256, sha1, md5) - hash_algorithm: sha256 - - # Skip hashing for system processes - skip_system_processes: true - - # Skip hashing for temporary files - skip_temp_files: true - - # Maximum hash computation time per process (ms) - max_hash_time_ms: 5000 - - # Enable enhanced process metadata collection - enable_enhanced_metadata: false -``` - -### Detection Engine Settings - -```yaml -detection: - # Path to detection rules directory - rules_path: /etc/daemoneye/rules - - # Enable rule hot-reloading - enable_hot_reload: true - - # Rule execution timeout in seconds - rule_timeout_secs: 30 - - # Maximum memory per rule execution (MB) - max_rule_memory_mb: 128 - - # Enable rule performance monitoring - enable_rule_metrics: true - - # Rule execution concurrency - max_concurrent_rules: 10 - - # Enable rule validation - enable_rule_validation: true -``` - -## Alerting Configuration - -### Alert Sinks - -```yaml -alerting: - # Enable alerting - enabled: true - - # Alert deduplication window in minutes - dedupe_window_minutes: 60 - - # Maximum alert queue size - max_queue_size: 10000 - - # Alert processing concurrency - max_concurrent_deliveries: 5 - - # Sink configurations - sinks: - # Standard output sink - - type: stdout - enabled: true - format: json # json, text, csv - - # File output sink - - type: file - enabled: false - path: /var/log/daemoneye/alerts.json - format: json - rotation: - max_size_mb: 100 - max_files: 10 - - # Syslog sink - - type: syslog - enabled: true - facility: daemon - tag: daemoneye - host: localhost - port: 514 - protocol: udp # udp, tcp - - # Webhook sink - - type: webhook - enabled: false - url: https://your-siem.com/webhook - method: POST - headers: - Authorization: Bearer ${WEBHOOK_TOKEN} - Content-Type: application/json - timeout_secs: 30 - retry_attempts: 3 - retry_delay_ms: 1000 - - # Email sink - - type: email - enabled: false - smtp_host: smtp.example.com - smtp_port: 587 - smtp_username: ${SMTP_USERNAME} - smtp_password: ${SMTP_PASSWORD} - smtp_tls: true - from: daemoneye@example.com - to: [security@example.com] - subject: 'DaemonEye Alert: {severity} - {title}' -``` - -Additional sink types (Splunk HEC, Elasticsearch, Kafka, and others) are available in commercial tiers. - -### Alert Filtering - -```yaml -alerting: - # Global alert filters - filters: - # Minimum severity level - min_severity: low # low, medium, high, critical - - # Exclude specific rules - exclude_rules: [test-rule, debug-rule] - - # Include only specific rules - include_rules: [] # Empty means all rules - - # Exclude specific hosts - exclude_hosts: [test-server, dev-workstation] - - # Include only specific hosts - include_hosts: [] # Empty means all hosts - - # Time-based filtering - time_filters: - # Exclude alerts during maintenance windows - maintenance_windows: - - start: 02:00 - end: 04:00 - days: [sunday] - - start: 12:00 - end: 13:00 - days: [monday, tuesday, wednesday, thursday, friday] -``` - -## Database Configuration - -### Database Configuration (redb) - -```yaml -database: - # Database file path - path: /var/lib/daemoneye/events.redb - - # Data retention period in days - retention_days: 30 - - # Maximum database size in MB - max_size_mb: 10240 - - # Enable automatic cleanup - enable_cleanup: true - - # Cleanup interval in hours - cleanup_interval_hours: 24 - - # Cleanup batch size - cleanup_batch_size: 1000 -``` - -## Platform-Specific Configuration - -### Linux Configuration - -```yaml -platform: - linux: - # Enable process namespace monitoring - enable_namespace_monitoring: true - - # Enable cgroup monitoring - enable_cgroup_monitoring: true - - # Process collection method - collection_method: sysinfo - - # Privilege requirements - privileges: - # Required capabilities - capabilities: [SYS_PTRACE] - - # Drop privileges after initialization - drop_privileges: true - - # Privilege drop timeout in seconds - privilege_drop_timeout_secs: 30 -``` - -Kernel-level collection (eBPF) is available in commercial tiers. - -### Windows Configuration - -```yaml -platform: - windows: - # Enable registry monitoring - enable_registry_monitoring: false - - # Enable file system monitoring - enable_filesystem_monitoring: false - - # Process collection method - collection_method: sysinfo - - # Privilege requirements - privileges: - # Required privileges - privileges: [SeDebugPrivilege] - - # Drop privileges after initialization - drop_privileges: true -``` - -Kernel-level collection (ETW) is available in commercial tiers. - -### macOS Configuration - -```yaml -platform: - macos: - # Enable file system monitoring - enable_filesystem_monitoring: false - - # Enable network monitoring - enable_network_monitoring: false - - # Process collection method - collection_method: sysinfo - - # Privilege requirements - privileges: - # Required entitlements - entitlements: [com.apple.security.cs.allow-jit] - - # Drop privileges after initialization - drop_privileges: true -``` - -Kernel-level collection (EndpointSecurity) is available in commercial tiers. - -## Environment Variables - -### Core Variables - -```bash -# Application settings -export DAEMONEYE_LOG_LEVEL=info -export DAEMONEYE_SCAN_INTERVAL_MS=30000 -export DAEMONEYE_BATCH_SIZE=1000 -export DAEMONEYE_RETENTION_DAYS=30 - -# Database settings -export DAEMONEYE_DATABASE_PATH=/var/lib/daemoneye/events.redb -export DAEMONEYE_AUDIT_LEDGER_PATH=/var/lib/daemoneye/audit.sqlite - -# Alerting settings -export DAEMONEYE_ALERTING_ENABLED=true -export DAEMONEYE_WEBHOOK_URL=https://your-siem.com/webhook -export DAEMONEYE_WEBHOOK_TOKEN=your-webhook-token - -# Platform settings -export DAEMONEYE_ENABLE_EBPF=false -export DAEMONEYE_ENABLE_ETW=false -export DAEMONEYE_ENABLE_ENDPOINT_SECURITY=false -``` - -## Configuration Examples - -### Basic Production Configuration - -```yaml -# /etc/daemoneye/config.yaml -app: - scan_interval_ms: 30000 - batch_size: 1000 - log_level: info - -database: - path: /var/lib/daemoneye/events.redb - retention_days: 30 - max_size_mb: 10240 - enable_cleanup: true - -# EventBus broker configuration -broker: - socket_path: /tmp/daemoneye-eventbus.sock - startup_timeout_seconds: 30 - max_message_buffer_size: 10000 - -# Platform-specific settings -platform: - linux: - enable_ebpf: false - windows: - enable_etw: false - macos: - enable_endpoint_security: false -``` - -### High-Performance Configuration - -```yaml -# /etc/daemoneye/config.yaml -app: - scan_interval_ms: 15000 # More frequent scanning - batch_size: 2000 # Larger batches - log_level: warn # Less verbose logging - retention_days: 7 # Shorter retention - max_memory_mb: 1024 # More memory - enable_metrics: true - -collection: - enable_process_collection: true - enable_hash_computation: true - hash_algorithm: sha256 - skip_system_processes: true - max_hash_time_ms: 2000 # Faster hash computation - -detection: - rules_path: /etc/daemoneye/rules - enable_hot_reload: true - rule_timeout_secs: 15 # Faster rule execution - max_concurrent_rules: 20 # More concurrent rules - max_rule_memory_mb: 64 # Less memory per rule - -alerting: - enabled: true - dedupe_window_minutes: 30 - max_concurrent_deliveries: 10 - sinks: - - type: syslog - enabled: true - facility: daemon - tag: daemoneye - - type: kafka - enabled: true - brokers: [kafka.example.com:9092] - topic: daemoneye.alerts - batch_size: 100 - batch_timeout_ms: 1000 - -database: - event_store: - path: /var/lib/daemoneye/events.redb - max_size_mb: 20480 - wal_mode: true - wal_checkpoint_interval_secs: 60 - max_connections: 20 - retention: - process_data_days: 7 - alert_data_days: 30 - enable_cleanup: true - cleanup_interval_hours: 6 -``` - -### Airgapped Environment Configuration - -```yaml -# /etc/daemoneye/config.yaml -app: - scan_interval_ms: 60000 # Less frequent scanning - batch_size: 500 # Smaller batches - log_level: info - retention_days: 90 # Longer retention - enable_metrics: true - -collection: - enable_process_collection: true - enable_hash_computation: true - hash_algorithm: sha256 - skip_system_processes: true - -detection: - rules_path: /etc/daemoneye/rules - enable_hot_reload: false # Disable hot reload - rule_timeout_secs: 60 - max_concurrent_rules: 5 - -alerting: - enabled: true - dedupe_window_minutes: 120 - sinks: - - type: file - enabled: true - path: /var/log/daemoneye/alerts.json - format: json - rotation: - max_size_mb: 50 - max_files: 20 - - type: syslog - enabled: true - facility: daemon - tag: daemoneye - -database: - event_store: - path: /var/lib/daemoneye/events.redb - max_size_mb: 5120 - wal_mode: true - audit_ledger: - path: /var/lib/daemoneye/audit.sqlite - wal_mode: true - synchronous: FULL - journal_mode: WAL -``` - -## Troubleshooting - -### Configuration Validation - -```bash -# Validate configuration file -daemoneye-cli config validate /etc/daemoneye/config.yaml - -# Validate current configuration -daemoneye-cli config validate - -# Check for configuration issues -daemoneye-cli config check - -# Show effective configuration -daemoneye-cli config show --include-defaults -``` - -### Common Configuration Issues - -**Invalid YAML Syntax**: - -```bash -# Check YAML syntax -python -c "import yaml; yaml.safe_load(open('/etc/daemoneye/config.yaml'))" - -# Use online YAML validator -# https://www.yamllint.com/ -``` - -**Missing Required Fields**: - -```bash -# Check for missing required fields -daemoneye-cli config check --strict - -# Show configuration with defaults -daemoneye-cli config show --include-defaults -``` - -**Permission Issues**: - -```bash -# Check file permissions -ls -la /etc/daemoneye/config.yaml -ls -la /var/lib/daemoneye/ - -# Fix permissions -sudo chown daemoneye:daemoneye /var/lib/daemoneye/ -sudo chmod 755 /var/lib/daemoneye/ -``` - -**Environment Variable Issues**: - -```bash -# Check environment variables -env | grep DAEMONEYE - -# Test environment variable substitution -daemoneye-cli config show --environment -``` - -### Configuration Debugging - -**Enable Debug Logging**: - -```yaml -app: - log_level: debug -``` - -**Configuration Loading Debug**: - -```bash -# Show configuration loading process -daemoneye-cli config debug - -# Show configuration sources -daemoneye-cli config sources -``` - -**Test Configuration Changes**: - -```bash -# Test configuration without applying -daemoneye-cli config test /path/to/new-config.yaml - -# Apply configuration with validation -daemoneye-cli config apply /path/to/new-config.yaml --validate -``` - ---- - -*This configuration guide provides comprehensive information about configuring DaemonEye for different deployment scenarios. For additional help, consult the troubleshooting section or contact support.* diff --git a/docs/src/user-guides/operator-guide.md b/docs/src/user-guides/operator-guide.md deleted file mode 100644 index ee8a47b1..00000000 --- a/docs/src/user-guides/operator-guide.md +++ /dev/null @@ -1,812 +0,0 @@ -# DaemonEye Operator Guide - -This guide provides comprehensive instructions for operators managing DaemonEye in production environments. It covers day-to-day operations, troubleshooting, and advanced configuration. - -## Table of Contents - -- [System Overview](#system-overview) -- [Basic Operations](#basic-operations) -- [Process Monitoring](#process-monitoring) -- [Alert Management](#alert-management) -- [Rule Management](#rule-management) -- [System Health Monitoring](#system-health-monitoring) -- [Configuration Management](#configuration-management) -- [Troubleshooting](#troubleshooting) -- [Best Practices](#best-practices) - -## System Overview - -### Component Status - -Check the overall health of your DaemonEye installation: - -```bash -# Overall system health -daemoneye-cli health - -# Component-specific health -daemoneye-cli health --component procmond -daemoneye-cli health --component daemoneye-agent -daemoneye-cli health --component database -``` - -**Expected Output**: - -```text -System Health: Healthy -├── procmond: Running (PID: 1234) -├── daemoneye-agent: Running (PID: 1235) -├── database: Connected -└── alerting: All sinks operational -``` - -### Service Management - -**Start Services**: - -```bash -# Linux (systemd) -sudo systemctl start daemoneye - -# macOS (launchd) -sudo launchctl load /Library/LaunchDaemons/com.daemoneye.agent.plist - -# Windows (Service) -sc start "DaemonEye Agent" -``` - -**Stop Services**: - -```bash -# Linux (systemd) -sudo systemctl stop daemoneye - -# macOS (launchd) -sudo launchctl unload /Library/LaunchDaemons/com.daemoneye.agent.plist - -# Windows (Service) -sc stop "DaemonEye Agent" -``` - -**Restart Services**: - -```bash -# Linux (systemd) -sudo systemctl restart daemoneye - -# macOS (launchd) -sudo launchctl unload /Library/LaunchDaemons/com.daemoneye.agent.plist -sudo launchctl load /Library/LaunchDaemons/com.daemoneye.agent.plist - -# Windows (Service) -sc stop "DaemonEye Agent" -sc start "DaemonEye Agent" -``` - -## Basic Operations - -### Querying Process Data - -**List Recent Processes**: - -```bash -# Last 10 processes -daemoneye-cli query "SELECT pid, name, executable_path, collection_time FROM processes ORDER BY collection_time DESC LIMIT 10" - -# Processes by name -daemoneye-cli query "SELECT * FROM processes WHERE name = 'chrome'" - -# High CPU processes -daemoneye-cli query "SELECT pid, name, cpu_usage FROM processes WHERE cpu_usage > 50.0 ORDER BY cpu_usage DESC" -``` - -**Process Tree Analysis**: - -```bash -# Find child processes of a specific parent -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' -" - -# Process hierarchy depth -daemoneye-cli query " -WITH RECURSIVE process_tree AS ( - SELECT pid, ppid, name, 0 as depth - FROM processes - WHERE ppid IS NULL - UNION ALL - SELECT p.pid, p.ppid, p.name, pt.depth + 1 - FROM processes p - JOIN process_tree pt ON p.ppid = pt.pid -) -SELECT pid, name, depth FROM process_tree ORDER BY depth, pid -" -``` - -**Suspicious Process Patterns**: - -```bash -# Processes with suspicious names -daemoneye-cli query " -SELECT pid, name, executable_path, command_line -FROM processes -WHERE name IN ('malware.exe', 'backdoor.exe', 'trojan.exe') - OR name LIKE '%suspicious%' - OR executable_path LIKE '%temp%' -" - -# Processes with unusual parent-child relationships -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 = 'explorer.exe' - AND p2.name NOT IN ('chrome.exe', 'firefox.exe', 'notepad.exe') -" -``` - -### Data Export - -**Export to Different Formats**: - -```bash -# JSON export -daemoneye-cli query "SELECT * FROM processes WHERE cpu_usage > 10.0" --format json > high_cpu_processes.json - -# CSV export -daemoneye-cli query "SELECT pid, name, cpu_usage, memory_usage FROM processes" --format csv > process_metrics.csv - -# Table format (default) -daemoneye-cli query "SELECT * FROM processes LIMIT 5" --format table -``` - -**Export with Filters**: - -```bash -# Export processes from last hour -daemoneye-cli query " -SELECT * FROM processes -WHERE collection_time > (strftime('%s', 'now') - 3600) * 1000 -" --format json > recent_processes.json - -# Export by user -daemoneye-cli query " -SELECT * FROM processes -WHERE user_id = '1000' -" --format csv > user_processes.csv -``` - -## Process Monitoring - -### Real-time Monitoring - -**Watch Process Activity**: - -```bash -# Monitor new processes in real-time -daemoneye-cli watch processes --filter "name LIKE '%chrome%'" - -# Monitor high CPU processes -daemoneye-cli watch processes --filter "cpu_usage > 50.0" - -# Monitor specific user processes -daemoneye-cli watch processes --filter "user_id = '1000'" -``` - -**Process Statistics**: - -```bash -# Process count by name -daemoneye-cli query " -SELECT name, COUNT(*) as count -FROM processes -GROUP BY name -ORDER BY count DESC -LIMIT 10 -" - -# CPU usage distribution -daemoneye-cli query " -SELECT - CASE - WHEN cpu_usage IS NULL THEN 'Unknown' - WHEN cpu_usage = 0 THEN '0%' - WHEN cpu_usage < 10 THEN '1-9%' - WHEN cpu_usage < 50 THEN '10-49%' - WHEN cpu_usage < 100 THEN '50-99%' - ELSE '100%+' - END as cpu_range, - COUNT(*) as process_count -FROM processes -GROUP BY cpu_range -ORDER BY process_count DESC -" - -# Memory usage statistics -daemoneye-cli query " -SELECT - AVG(memory_usage) as avg_memory, - MIN(memory_usage) as min_memory, - MAX(memory_usage) as max_memory, - COUNT(*) as process_count -FROM processes -WHERE memory_usage IS NOT NULL -" -``` - -### Process Investigation - -**Deep Process Analysis**: - -```bash -# Get detailed information about a specific process -daemoneye-cli query " -SELECT - pid, - name, - executable_path, - command_line, - start_time, - cpu_usage, - memory_usage, - executable_hash, - user_id, - collection_time -FROM processes -WHERE pid = 1234 -" - -# Find processes with the same executable -daemoneye-cli query " -SELECT - executable_path, - COUNT(*) as instance_count, - GROUP_CONCAT(pid) as pids -FROM processes -WHERE executable_path IS NOT NULL -GROUP BY executable_path -HAVING COUNT(*) > 1 -ORDER BY instance_count DESC -" - -# Process execution timeline -daemoneye-cli query " -SELECT - pid, - name, - collection_time, - cpu_usage, - memory_usage -FROM processes -WHERE name = 'chrome' -ORDER BY collection_time DESC -LIMIT 20 -" -``` - -## Alert Management - -### Viewing Alerts - -**List Recent Alerts**: - -```bash -# Last 10 alerts -daemoneye-cli alerts list --limit 10 - -# Alerts by severity -daemoneye-cli alerts list --severity high,critical - -# Alerts by rule -daemoneye-cli alerts list --rule "suspicious-processes" - -# Alerts from specific time range -daemoneye-cli alerts list --since "2024-01-15 10:00:00" --until "2024-01-15 18:00:00" -``` - -**Alert Details**: - -```bash -# Get detailed information about a specific alert -daemoneye-cli alerts show - -# Export alerts to file -daemoneye-cli alerts export --format json --output alerts.json - -# Export alerts with filters -daemoneye-cli alerts export --severity high,critical --format csv --output critical_alerts.csv -``` - -### Alert Filtering and Search - -**Advanced Alert Queries**: - -```bash -# Alerts affecting specific processes -daemoneye-cli query " -SELECT - a.id, - a.title, - a.severity, - a.alert_time, - a.affected_processes -FROM alerts a -WHERE JSON_EXTRACT(a.alert_data, '$.pid') = 1234 -ORDER BY a.alert_time DESC -" - -# Alerts by hostname -daemoneye-cli query " -SELECT - a.id, - a.title, - a.severity, - a.alert_time, - JSON_EXTRACT(a.alert_data, '$.hostname') as hostname -FROM alerts a -WHERE JSON_EXTRACT(a.alert_data, '$.hostname') = 'server-01' -ORDER BY a.alert_time DESC -" - -# Alert frequency by rule -daemoneye-cli query " -SELECT - rule_id, - COUNT(*) as alert_count, - MAX(alert_time) as last_alert -FROM alerts -GROUP BY rule_id -ORDER BY alert_count DESC -" -``` - -### Alert Response - -**Acknowledge Alerts**: - -```bash -# Acknowledge a specific alert -daemoneye-cli alerts acknowledge --comment "Investigating" - -# Acknowledge multiple alerts -daemoneye-cli alerts acknowledge --rule "suspicious-processes" --comment "False positive" - -# List acknowledged alerts -daemoneye-cli alerts list --status acknowledged -``` - -**Alert Suppression**: - -```bash -# Suppress alerts for a specific rule -daemoneye-cli alerts suppress --rule "suspicious-processes" --duration "1h" --reason "Maintenance" - -# Suppress alerts for specific processes -daemoneye-cli alerts suppress --process 1234 --duration "30m" --reason "Known good process" - -# List active suppressions -daemoneye-cli alerts suppressions list -``` - -## Rule Management - -### Rule Operations - -**List Rules**: - -```bash -# List all rules -daemoneye-cli rules list - -# List enabled rules only -daemoneye-cli rules list --enabled - -# List rules by category -daemoneye-cli rules list --category "malware" - -# List rules by severity -daemoneye-cli rules list --severity high,critical -``` - -**Rule Validation**: - -```bash -# Validate a rule file -daemoneye-cli rules validate /path/to/rule.sql - -# Validate all rules -daemoneye-cli rules validate --all - -# Test a rule with sample data -daemoneye-cli rules test /path/to/rule.sql --sample-data -``` - -**Rule Management**: - -```bash -# Enable a rule -daemoneye-cli rules enable suspicious-processes - -# Disable a rule -daemoneye-cli rules disable suspicious-processes - -# Update a rule -daemoneye-cli rules update suspicious-processes --file /path/to/new-rule.sql - -# Delete a rule -daemoneye-cli rules delete suspicious-processes -``` - -### Rule Development - -**Create a New Rule**: - -```bash -# Create a new rule file -cat > /etc/daemoneye/rules/custom-rule.sql << 'EOF' --- 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; -EOF - -# Validate the rule -daemoneye-cli rules validate /etc/daemoneye/rules/custom-rule.sql - -# Enable the rule -daemoneye-cli rules enable custom-rule -``` - -**Rule Testing**: - -```bash -# Test rule against current data -daemoneye-cli rules test custom-rule --live - -# Test rule with specific time range -daemoneye-cli rules test custom-rule --since "2024-01-15 00:00:00" --until "2024-01-15 23:59:59" - -# Test rule performance -daemoneye-cli rules test custom-rule --benchmark -``` - -### Rule Import/Export - -**Export Rules**: - -```bash -# Export all rules -daemoneye-cli rules export --output rules-backup.tar.gz - -# Export specific rules -daemoneye-cli rules export --rules "suspicious-processes,high-cpu" --output selected-rules.tar.gz - -# Export rules by category -daemoneye-cli rules export --category "malware" --output malware-rules.tar.gz -``` - -**Import Rules**: - -```bash -# Import rules from file -daemoneye-cli rules import rules-backup.tar.gz - -# Import rules with validation -daemoneye-cli rules import rules-backup.tar.gz --validate - -# Import rules with conflict resolution -daemoneye-cli rules import rules-backup.tar.gz --resolve-conflicts -``` - -## System Health Monitoring - -### Performance Metrics - -**System Performance**: - -```bash -# View system metrics -daemoneye-cli metrics - -# CPU usage over time -daemoneye-cli metrics --metric cpu_usage --duration 1h - -# Memory usage over time -daemoneye-cli metrics --metric memory_usage --duration 1h - -# Process collection rate -daemoneye-cli metrics --metric collection_rate --duration 1h -``` - -**Database Performance**: - -```bash -# Database status -daemoneye-cli database status - -# Database size -daemoneye-cli database size - -# Database performance metrics -daemoneye-cli database metrics - -# Database maintenance -daemoneye-cli database maintenance --vacuum -``` - -### Log Analysis - -**View Logs**: - -```bash -# Recent logs -daemoneye-cli logs --tail 50 - -# Logs by level -daemoneye-cli logs --level error - -# Logs by component -daemoneye-cli logs --component procmond - -# Logs with filters -daemoneye-cli logs --filter "error" --tail 100 -``` - -**Log Analysis**: - -```bash -# Error frequency -daemoneye-cli logs --analyze --level error - -# Performance issues -daemoneye-cli logs --analyze --filter "slow" - -# Security events -daemoneye-cli logs --analyze --filter "security" -``` - -## Configuration Management - -### Configuration Files - -**View Configuration**: - -```bash -# Show current configuration -daemoneye-cli config show - -# Show specific configuration section -daemoneye-cli config show alerting - -# Show configuration with defaults -daemoneye-cli config show --include-defaults -``` - -**Update Configuration**: - -```bash -# Update configuration value -daemoneye-cli config set app.scan_interval_ms 60000 - -# Update multiple values -daemoneye-cli config set alerting.sinks[0].enabled true - -# Reload configuration -daemoneye-cli config reload -``` - -**Configuration Validation**: - -```bash -# Validate configuration file -daemoneye-cli config validate /etc/daemoneye/config.yaml - -# Validate current configuration -daemoneye-cli config validate - -# Check configuration for issues -daemoneye-cli config check -``` - -### Environment Management - -**Environment Variables**: - -```bash -# Set environment variables -export DAEMONEYE_LOG_LEVEL=debug -export DAEMONEYE_DATABASE_PATH=/var/lib/daemoneye/events.redb - -# View environment configuration -daemoneye-cli config show --environment -``` - -**Service Configuration**: - -```bash -# Update service configuration -sudo systemctl edit daemoneye - -# Reload service configuration -sudo systemctl daemon-reload -sudo systemctl restart daemoneye -``` - -## Troubleshooting - -### Common Issues - -**Service Won't Start**: - -```bash -# Check service status -sudo systemctl status daemoneye - -# Check logs for errors -sudo journalctl -u daemoneye -f - -# Check configuration -daemoneye-cli config validate - -# Check permissions -ls -la /var/lib/daemoneye/ -``` - -**Database Issues**: - -```bash -# Check database status -daemoneye-cli database status - -# Check database integrity -daemoneye-cli database integrity-check - -# Repair database -daemoneye-cli database repair - -# Rebuild database -daemoneye-cli database rebuild -``` - -**Alert Delivery Issues**: - -```bash -# Check alert sink status -daemoneye-cli alerts sinks status - -# Test alert delivery -daemoneye-cli alerts test-delivery - -# Check network connectivity -daemoneye-cli network test - -# View delivery logs -daemoneye-cli logs --filter "delivery" -``` - -### Debug Mode - -**Enable Debug Logging**: - -```bash -# Set debug log level -daemoneye-cli config set app.log_level debug - -# Restart service -sudo systemctl restart daemoneye - -# Monitor debug logs -daemoneye-cli logs --level debug --tail 100 -``` - -**Component Debugging**: - -```bash -# Debug procmond -sudo daemoneye-cli debug procmond --verbose - -# Debug daemoneye-agent -daemoneye-cli debug daemoneye-agent --verbose - -# Debug database -daemoneye-cli debug database --verbose -``` - -### Performance Issues - -**High CPU Usage**: - -```bash -# Check process collection rate -daemoneye-cli metrics --metric collection_rate - -# Reduce scan interval -daemoneye-cli config set app.scan_interval_ms 60000 - -# Check for problematic rules -daemoneye-cli rules list --performance -``` - -**High Memory Usage**: - -```bash -# Check memory usage -daemoneye-cli metrics --metric memory_usage - -# Reduce batch size -daemoneye-cli config set app.batch_size 500 - -# Check database size -daemoneye-cli database size -``` - -**Slow Queries**: - -```bash -# Check query performance -daemoneye-cli database query-stats - -# Optimize database -daemoneye-cli database optimize - -# Check for slow rules -daemoneye-cli rules list --slow -``` - -## Best Practices - -### Security - -1. **Regular Updates**: Keep DaemonEye updated to the latest version -2. **Access Control**: Limit access to DaemonEye configuration and data -3. **Audit Logging**: Enable comprehensive audit logging -4. **Network Security**: Use secure connections for remote management -5. **Backup**: Regularly backup configuration and database - -### Performance - -1. **Resource Monitoring**: Monitor CPU, memory, and disk usage -2. **Rule Optimization**: Optimize detection rules for performance -3. **Database Maintenance**: Regular database maintenance and cleanup -4. **Alert Tuning**: Tune alert thresholds to reduce noise -5. **Capacity Planning**: Plan for growth in process count and data volume - -### Operations - -1. **Documentation**: Document custom rules and configurations -2. **Testing**: Test rules and configurations in non-production environments -3. **Monitoring**: Set up comprehensive monitoring and alerting -4. **Incident Response**: Develop procedures for security incidents -5. **Training**: Train operators on DaemonEye features and best practices - -### Maintenance - -1. **Regular Backups**: Backup configuration and database regularly -2. **Log Rotation**: Implement log rotation to prevent disk space issues -3. **Database Cleanup**: Regular cleanup of old data -4. **Rule Review**: Regular review and update of detection rules -5. **Performance Tuning**: Regular performance analysis and tuning - ---- - -*This operator guide provides comprehensive instructions for managing DaemonEye in production environments. For additional help, consult the troubleshooting section or contact support.* From 928ea193421130c3cb58738dd2e1de14f3aa75a6 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Sun, 26 Apr 2026 11:10:37 -0400 Subject: [PATCH 02/11] docs(steering): scrub paid-tier specifics from steering and spec docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Steering docs are auto-loaded into agent context, so paid-tier feature enumerations there are direct violations of the open-core hygiene rule in AGENTS.md. Equivalent commercial-tier content is preserved in Confluence space ES (Feature Tiers 1802352, Business Tier 1802362, Enterprise Tier 1802363, Architecture Overview 1802349). Removed: - .kiro/steering/product.md — pure paid-tier product overview (Free/Business/Enterprise tier tables); superseded by Confluence PRD 11599874 and the Project Overview pages - spec/structure.md — older duplicate of .kiro/steering/structure.md - spec/tech.md — older duplicate of .kiro/steering/tech.md Edited: - .kiro/steering/structure.md * Removed phantom security-center/ and project_spec/ entries from workspace tree * Replaced Free/Business/Enterprise "Deployment Tiers" enumeration with a single boundary-acknowledgement footnote * Removed the security-center/ component subsection * Replaced it with collector-core/ and daemoneye-eventbus/ subsections that actually exist in this repo * Dropped Business/Enterprise Tables subsection from Database Schema Design and the federated-storage / kernel-event bullets from Access Patterns - .kiro/steering/tech.md * Trimmed Phase 3 ("kernel-level real-time monitoring (Enterprise tier)") from the Process Enumeration phasing list * Removed the Kernel Monitoring (Enterprise Tier) subsection * Removed the Enterprise Security Features subsection * Added a single boundary footnote for kernel-level monitoring Signed-off-by: UncleSp1d3r --- .kiro/steering/product.md | 78 ------------- .kiro/steering/structure.md | 48 +++----- .kiro/steering/tech.md | 17 +-- spec/structure.md | 205 --------------------------------- spec/tech.md | 220 ------------------------------------ 5 files changed, 20 insertions(+), 548 deletions(-) delete mode 100644 .kiro/steering/product.md delete mode 100644 spec/structure.md delete mode 100644 spec/tech.md diff --git a/.kiro/steering/product.md b/.kiro/steering/product.md deleted file mode 100644 index ea43b28b..00000000 --- a/.kiro/steering/product.md +++ /dev/null @@ -1,78 +0,0 @@ -# DaemonEye Product Overview - -DaemonEye is a security-focused, high-performance process monitoring system built for cybersecurity professionals, threat hunters, and security operations centers. **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. - -## 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**: Tamper-evident, cryptographically chained logs suitable for compliance and forensics -- **Offline-First Operation**: Full functionality without internet access, perfect for airgapped environments -- **Security-First Architecture**: Privilege separation, sandboxed execution, and minimal attack surface -- **High Performance**: \<5% CPU overhead while monitoring 10,000+ processes with sub-second enumeration -- **Operator-Centric Design**: Built for operators, by operators, with workflows optimized for contested environments - -## Three-Component Architecture - -1. **procmond** (Privileged Process Collector): Runs with elevated privileges, focused solely on process monitoring with minimal attack surface. Communicates via protobuf IPC with daemoneye-agent. -2. **daemoneye-agent** (User-Space Orchestrator): Operates in user space with minimal privileges for alerting and network delivery. Manages procmond lifecycle and translates SQL rules to simple detection tasks. -3. **daemoneye-cli** (Command-Line Interface): Local interface for data queries, result exports, and service configuration. Communicates with daemoneye-agent for all operations. - -## Tiered Deployment Architecture - -### Free Tier - -- Standalone agent deployment (procmond + daemoneye-agent + daemoneye-cli) -- Local process monitoring and detection -- Basic alerting and data export - -### Business Tier - -- **Security Center**: Centralized management and aggregation -- **Enterprise Integrations**: Splunk, Elasticsearch, Kafka connectors -- **Curated Rule Packs**: Pre-built detection rules for common threats -- **Container Support**: Kubernetes DaemonSet deployment -- **Code Signing**: Signed installers for Windows/macOS - -### Enterprise Tier (Custom Pricing) - -- **Kernel-Level Monitoring**: Real-time eBPF/ETW/EndpointSecurity -- **Federated Architecture**: Multi-tier Security Center hierarchy -- **Advanced SIEM Integration**: STIX/TAXII, compliance mappings -- **Hardened Security**: SLSA provenance, Cosign signatures -- **Network Correlation**: Process-to-network event correlation - -## Target 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 - -## Key Features - -### Threat Detection Capabilities - -- **Process Behavior Analysis**: Detect process hollowing, executable integrity violations, suspicious parent-child relationships -- **Anomaly Detection**: Identify unusual resource consumption patterns and suspicious process name duplications -- **SQL-Based Detection Engine**: Flexible rule creation using standard SQL queries with sandboxed execution -- **Built-in Detection Rules**: Comprehensive library covering common threat patterns and attack techniques - -### System Integration - -- Cross-platform support (Linux, macOS, Windows) with native OS integration -- Multi-channel alerting (stdout, syslog, webhooks, email) for SIEM integration -- Tamper-evident audit logging with BLAKE3 cryptographic integrity for forensic analysis -- Resource-bounded operation with graceful degradation under load -- Offline-first operation with bundle-based configuration distribution - -### Enterprise Features - -- **Federated Management**: Multi-tier Security Center architecture for large deployments -- **Real-time Monitoring**: Kernel-level event subscription (eBPF, ETW, EndpointSecurity) -- **Advanced Integrations**: STIX/TAXII feeds, compliance framework mappings -- **Hardened Security**: SLSA Level 3 provenance, hardware-backed code signing -- **Network Correlation**: Process-to-network event correlation for lateral movement detection diff --git a/.kiro/steering/structure.md b/.kiro/steering/structure.md index 2fe5e109..52fdcbf4 100644 --- a/.kiro/steering/structure.md +++ b/.kiro/steering/structure.md @@ -2,23 +2,19 @@ ## Workspace Organization -DaemonEye follows a **three-component security architecture** with strict privilege separation, extensible to multi-tier deployments: +DaemonEye follows a **three-component security architecture** with strict privilege separation: ```text DaemonEye/ -├── procmond/ # Privileged Process Collector -├── daemoneye-agent/ # User-Space Orchestrator -├── daemoneye-cli/ # Command-Line Interface -├── daemoneye-lib/ # Shared Library Components -├── security-center/ # Centralized Management (Business/Enterprise) -└── project_spec/ # Project Documentation +├── procmond/ # Privileged Process Collector +├── daemoneye-agent/ # User-Space Orchestrator +├── daemoneye-cli/ # Command-Line Interface +├── daemoneye-lib/ # Shared Library Components +├── collector-core/ # Collector SDK (EventSource trait, runtime, IPC) +└── daemoneye-eventbus/ # Embedded broker for cross-process pub/sub and RPC ``` -**Deployment Tiers:** - -- **Free Tier**: Standalone agents (procmond + daemoneye-agent + daemoneye-cli) -- **Business Tier**: + Security Center + Enterprise integrations -- **Enterprise Tier**: + Kernel monitoring + Federated architecture + Advanced SIEM +> This repository contains the Community tier. Commercial tiers (fleet management, GUI, federation, kernel-level collectors) extend this foundation and are sold separately, not in this repo. See evilbitlabs.io for commercial details. ## Component Responsibilities @@ -47,15 +43,19 @@ DaemonEye/ ### daemoneye-lib/ (Shared Core) - **Purpose**: Common functionality shared across all components -- **Modules**: config, models, storage, detection, alerting, crypto, telemetry, kernel, network +- **Modules**: config, models, storage, detection, alerting, crypto, telemetry - **Security**: Trait-based abstractions with security boundaries -### security-center/ (Centralized Management) +### collector-core/ (Collector SDK) + +- **Purpose**: SDK providing shared operational infrastructure for collectors (`EventSource` trait, `Collector` runtime, capability negotiation, lifecycle management, IPC contracts) +- **Contract**: Protobuf IPC (`ipc.proto`, `eventbus.proto`) — language-neutral boundary + +### daemoneye-eventbus/ (Embedded Broker) -- **Purpose**: Centralized aggregation and management for Business/Enterprise tiers -- **Security**: mTLS authentication, certificate management, role-based access -- **Features**: Fleet management, rule distribution, data aggregation, web GUI -- **Deployment**: Optional component for multi-agent environments +- **Purpose**: Cross-process pub/sub and RPC broker embedded inside daemoneye-agent +- **Features**: Topic hierarchy with wildcard subscriptions, correlation metadata, RPC patterns for collector lifecycle management +- **Transport**: Unix domain sockets (Linux/macOS), named pipes (Windows) ## Coding Standards @@ -133,24 +133,12 @@ Hierarchical configuration with clear precedence: - **alert_deliveries**: Delivery tracking with retry information - **audit_ledger**: Tamper-evident cryptographic chain -### Business/Enterprise Tables - -- **agents**: Agent registration and status tracking -- **agent_connections**: mTLS connection management and certificates -- **fleet_events**: Centralized event aggregation from multiple agents -- **rule_packs**: Curated rule pack management and distribution -- **compliance_mappings**: Compliance framework mappings (NIST, ISO 27001, CIS) -- **network_events**: Network activity correlation (Enterprise tier) -- **kernel_events**: Kernel-level event monitoring (Enterprise tier) - ### Access Patterns - **Event Store**: redb with concurrent access and ACID transactions - **Audit Ledger**: redb with write-only access for procmond - **Detection Queries**: Read-only database connections for rule execution - **Indexing**: Optimized for time-series queries and rule execution -- **Federated Storage**: Hierarchical data aggregation across Security Centers -- **Real-time Events**: Kernel-level event streaming (Enterprise tier) ### IPC Protocol diff --git a/.kiro/steering/tech.md b/.kiro/steering/tech.md index f9571e79..19abd261 100644 --- a/.kiro/steering/tech.md +++ b/.kiro/steering/tech.md @@ -126,16 +126,10 @@ just run-daemoneye-agent --config /path # Run orchestrator agent ### Process Enumeration - **Phase 1**: sysinfo crate for unified cross-platform baseline -- **Phase 2**: Platform-specific enhancements (eBPF, ETW, EndpointSecurity) -- **Phase 3**: Kernel-level real-time monitoring (Enterprise tier) +- **Phase 2**: Platform-specific enhancements (Planned) - **Fallback**: Graceful degradation when enhanced features unavailable -### Kernel Monitoring (Enterprise Tier) - -- **Linux**: eBPF programs for real-time process and syscall monitoring -- **Windows**: ETW integration for kernel events and registry monitoring -- **macOS**: EndpointSecurity framework for process and file system events -- **Network**: Platform-specific network event correlation +> Kernel-level monitoring (eBPF / ETW / EndpointSecurity) is provided by commercial tier collectors that are sold separately, not in this repo. ### Privilege Management @@ -143,13 +137,6 @@ just run-daemoneye-agent --config /path # Run orchestrator agent - **Windows**: SeDebugPrivilege, token restriction after init - **macOS**: Minimal entitlements, sandbox compatibility -### Enterprise Security Features - -- **Authentication**: mTLS with certificate chain validation -- **Code Signing**: SLSA Level 3 provenance, Cosign signatures -- **Compliance**: NIST, ISO 27001, CIS framework mappings -- **Threat Intelligence**: STIX/TAXII integration, quarterly rule packs - ## Testing Strategy ### Test Runner & Framework diff --git a/spec/structure.md b/spec/structure.md deleted file mode 100644 index 61000d5c..00000000 --- a/spec/structure.md +++ /dev/null @@ -1,205 +0,0 @@ -# DaemonEye Project Structure - -## Workspace Organization - -DaemonEye follows a **three-component security architecture** with strict privilege separation, extensible to multi-tier deployments: - -```text -DaemonEye/ -├── procmond/ # Privileged Process Collector -├── daemoneye-agent/ # User-Space Orchestrator -├── daemoneye-cli/ # Command-Line Interface -├── daemoneye-lib/ # Shared Library Components -├── security-center/ # Centralized Management (Business/Enterprise) -└── project_spec/ # Project Documentation -``` - -**Deployment Tiers:** - -- **Free Tier**: Standalone agents (procmond + daemoneye-agent + daemoneye-cli) -- **Business Tier**: + Security Center + Enterprise integrations -- **Enterprise Tier**: + Kernel monitoring + Federated architecture + Advanced SIEM - -## Component Responsibilities - -### procmond/ (Privileged Collector) - -- **Purpose**: Minimal privileged component for process data collection -- **Security**: Runs with elevated privileges, drops them immediately after init -- **Network**: No network access whatsoever -- **Database**: Write-only access to audit ledger -- **Communication**: IPC server for receiving simple detection tasks from daemoneye-agent - -### daemoneye-agent/ (Detection Orchestrator) - -- **Purpose**: User-space detection rule execution and alert dispatching -- **Security**: Minimal privileges, outbound-only network connections -- **Database**: Read/write access to event store, manages procmond lifecycle -- **Features**: SQL-based detection engine, multi-channel alerting, IPC client -- **Communication**: Translates complex SQL rules into simple protobuf tasks for procmond - -### daemoneye-cli/ (Operator Interface) - -- **Purpose**: User-friendly CLI for queries, exports, and configuration -- **Security**: No network access, read-only database operations -- **Features**: JSON/table output, color handling, shell completions - -### daemoneye-lib/ (Shared Core) - -- **Purpose**: Common functionality shared across all components -- **Modules**: config, models, storage, detection, alerting, crypto, telemetry, kernel, network -- **Security**: Trait-based abstractions with security boundaries - -### security-center/ (Centralized Management) - -- **Purpose**: Centralized aggregation and management for Business/Enterprise tiers -- **Security**: mTLS authentication, certificate management, role-based access -- **Features**: Fleet management, rule distribution, data aggregation, web GUI -- **Deployment**: Optional component for multi-agent environments - -## Coding Standards - -### Workspace Configuration - -- **Edition**: Rust 2024 (MSRV: 1.91+) -- **Resolver**: Version 3 for enhanced dependency resolution -- **Lints**: `unsafe_code = "forbid"`, `warnings = "deny"` -- **Quality**: Zero-warnings policy enforced by CI - -### Module Organization - -```rust,ignore -// Library structure pattern -pub mod alerting; // Multi-channel alert delivery -pub mod config; // Configuration management -pub mod crypto; // Cryptographic audit functions -pub mod detection; // SQL-based detection engine -pub mod models; // Core data structures -pub mod storage; // Database abstractions -``` - -### Error Handling Pattern - -- **Libraries**: Use `thiserror` for structured error types -- **Applications**: Use `anyhow` for error context and chains -- **Recovery**: Graceful degradation with detailed error context -- **Logging**: Structured error events with tracing spans - -### Security Boundaries - -- **Database Access**: Component-specific access patterns (read-only vs write-only) -- **Network Access**: Strict outbound-only for daemoneye-agent, none for others -- **Privilege Separation**: Immediate privilege dropping after initialization -- **Input Validation**: Comprehensive validation at all boundaries - -## Development Workflow - -### Task Runner (justfile) - -All development tasks use the `just` command runner: - -- `just fmt` - Format code with rustfmt -- `just lint` - Run clippy with strict warnings -- `just test` - Run comprehensive test suite -- `just build` - Build entire workspace - -### Testing Architecture - -- **Unit Tests**: Component-specific functionality testing -- **Integration Tests**: Cross-component interaction testing -- **CLI Tests**: insta for snapshot testing of command-line interface -- **Performance Tests**: Criterion benchmarks with regression detection - -### Configuration Management - -Hierarchical configuration with clear precedence: - -1. Command-line flags (highest precedence) -2. Environment variables (`DaemonEye_*`) -3. User configuration files (`~/.config/DaemonEye/`) -4. System configuration files (`/etc/DaemonEye/`) -5. Embedded defaults (lowest precedence) - -## Database Schema Design - -### Core Tables - -- **processes**: Process snapshots with comprehensive metadata -- **scans**: Collection cycle metadata and statistics -- **detection_rules**: Rule definitions with versioning (rules translated to simple tasks for procmond) -- **alerts**: Generated alerts with execution context -- **alert_deliveries**: Delivery tracking with retry information -- **audit_ledger**: Tamper-evident cryptographic chain - -### Business/Enterprise Tables - -- **agents**: Agent registration and status tracking -- **agent_connections**: mTLS connection management and certificates -- **fleet_events**: Centralized event aggregation from multiple agents -- **rule_packs**: Curated rule pack management and distribution -- **compliance_mappings**: Compliance framework mappings (NIST, ISO 27001, CIS) -- **network_events**: Network activity correlation (Enterprise tier) -- **kernel_events**: Kernel-level event monitoring (Enterprise tier) - -### Access Patterns - -- **Event Store**: redb with concurrent access and ACID transactions -- **Audit Ledger**: redb with write-only access for procmond -- **Detection Queries**: Read-only database connections for rule execution -- **Indexing**: Optimized for time-series queries and rule execution -- **Federated Storage**: Hierarchical data aggregation across Security Centers -- **Real-time Events**: Kernel-level event streaming (Enterprise tier) - -### IPC Protocol - -- **Transport**: Unix domain sockets (Linux/macOS), named pipes (Windows) -- **Format**: Custom protobuf messages for DetectionTask and DetectionResult -- **Security**: Connection authentication and optional encryption -- **Reliability**: Automatic reconnection with exponential backoff - -## Security Architecture - -### Privilege Separation - -- Only procmond runs with elevated privileges when necessary -- Immediate privilege drop after initialization -- Detection and alerting run in user space - -### 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 - -## File Organization Conventions - -### Source Code Structure - -```text -src/ -├── main.rs # Binary entrypoint -├── lib.rs # Library interface (for libs) -├── commands/ # CLI subcommand implementations -├── platform/ # OS-specific implementations -└── [module].rs # Feature-specific modules -``` - -### Configuration Files - -- **System**: `/etc/DaemonEye/config.yaml` -- **User**: `~/.config/DaemonEye/config.yaml` -- **Service**: Platform-specific service definitions in `scripts/service/` - -### Documentation Structure - -- **Specifications**: `project_spec/` directory with comprehensive docs -- **API Documentation**: Generated from code with `cargo doc` -- **Operator Guide**: User-facing documentation in `docs/` diff --git a/spec/tech.md b/spec/tech.md deleted file mode 100644 index ce7fab49..00000000 --- a/spec/tech.md +++ /dev/null @@ -1,220 +0,0 @@ -# DaemonEye Technical Stack - -## Language & Runtime - -- **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 - -## Core Dependencies - -### Database Layer - -- **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 - -### IPC Communication - -- **Protocol**: Custom protobuf over Unix sockets (Linux/macOS) and named pipes (Windows) -- **Features**: Async message handling, automatic reconnection with exponential backoff -- **Security**: Connection authentication and optional encryption -- **Scope**: CLI-to-agent communication (daemoneye-cli ↔ daemoneye-agent) - -### EventBus and RPC Architecture - -- **daemoneye-eventbus**: Cross-platform IPC event bus with embedded broker architecture -- **Transport**: Unix domain sockets (Linux/macOS) and named pipes (Windows) -- **Messaging**: Topic-based pub/sub with hierarchical routing and wildcard patterns (`+`, `#`) -- **Performance**: 10,000+ messages/second throughput, sub-millisecond latency -- **Scope**: Multi-process coordination (daemoneye-agent ↔ collector-core components) -- **Embedded Broker**: Runs within daemoneye-agent process for local collector coordination -- **RPC Service**: Collector lifecycle management (start/stop/restart/health checks) -- **RPC Features**: Timeout handling, correlation tracking, error propagation, capability-based routing -- **Coordination**: Multi-collector task distribution, result aggregation, load balancing, failover -- **Correlation Metadata**: Distributed tracing with correlation IDs, sequence numbers, workflow stages - -### 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 - -## Build System & Commands - -### Task Runner (justfile) - -```bash -# Development workflow -just fmt # Format code with rustfmt -just lint # Run clippy with strict warnings (-D warnings) -just test # Run all tests with cargo-nextest (unit + integration) -just build # Build entire workspace - -# Testing variants -just test-ci # Run tests with nextest for CI -just test-fast # Run only fast unit tests -just coverage # Generate coverage report with llvm-cov - -# Benchmarking -just bench # Run all benchmarks -just bench-process # Run process collection benchmarks -just bench-database # Run database operation benchmarks - -# Component execution -just run-procmond --interval 30 --enhanced-metadata # Run process monitor -just run-daemoneye-cli --format json # Run CLI interface -just run-daemoneye-agent --log-level debug # Run orchestrator agent -``` - -### Build Configuration - -- **Profile**: Release builds with LTO, single codegen unit, stripped symbols -- **Cross-platform**: Static binaries with embedded SQLite -- **Packaging**: Platform-specific service files (systemd, launchd, Windows Service) - -## Performance Requirements - -- **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 - -## Security Architecture - -### SQL-to-IPC Architecture - -- **Detection Rule Processing**: SQL detection rules are never executed directly against live processes -- **AST Analysis**: sqlparser extracts collection requirements from SQL AST to generate protobuf tasks -- **Task Translation**: daemoneye-agent translates complex SQL queries into simple collection tasks for procmond -- **Overcollection Strategy**: procmond may overcollect data due to granularity limitations, then SQL runs against stored data -- **Privilege Separation**: Only procmond touches live processes; SQL execution remains in userspace -- **Query Validation**: Only SELECT statements with approved functions allowed in detection engine -- **Prepared Statements**: All database queries use parameterized statements only - -### Cryptographic Components - -- **Audit Ledger**: Certificate Transparency-style append-only log with Merkle tree structure -- **Hashing**: BLAKE3 for fast cryptographic hashing and Merkle tree construction -- **Merkle Trees**: `rs-merkle` for efficient inclusion/exclusion proofs and batch verification -- **Signatures**: Optional Ed25519 for audit entry signing and periodic root hash attestation -- **Integrity**: HMAC for message authentication and tamper detection -- **Verification**: Logarithmic proof sizes for efficient audit trail validation -- **Airgap Support**: Periodic root hash checkpoints for manual external verification - -### Resource Management - -- **Bounded Channels**: Configurable capacity with backpressure policies -- **Memory Limits**: Cooperative yielding and memory budget enforcement -- **Timeout Support**: Cancellation tokens for graceful shutdown -- **Circuit Breakers**: Reliability patterns for external dependencies - -## Cross-Platform Strategy - -### OS Support Matrix - -| OS | Version | Architecture | Status | Notes | -| ----------- | -------------------- | ------------- | --------- | ------------------------------ | -| **Linux** | Ubuntu 20.04+ LTS | x86_64, ARM64 | Primary | Full feature support | -| **Linux** | RHEL/CentOS 8+ | x86_64, ARM64 | Primary | Full feature support | -| **Linux** | Alma/Rocky Linux 8+ | x86_64, ARM64 | Primary | Full feature support | -| **Linux** | Debian 11+ LTS | x86_64, ARM64 | Primary | Full feature support | -| **macOS** | 14.0+ (Sonoma) | x86_64, ARM64 | Primary | Native process monitoring | -| **Windows** | Windows 10+ | x86_64, ARM64 | Primary | Service deployment[^5] | -| **Windows** | Windows Server 2019+ | x86_64 | Primary | Enterprise features[^6] | -| **Windows** | Windows Server 2022 | x86_64, ARM64 | Primary | Enterprise standard | -| **Windows** | Windows 11 | x86_64, ARM64 | Primary | Full feature support | -| **Linux** | Alpine 3.16+ | x86_64, ARM64 | Secondary | Container deployments | -| **Linux** | Amazon Linux 2+ | x86_64, ARM64 | Secondary | Cloud deployments | -| **Linux** | Ubuntu 18.04 | x86_64, ARM64 | Secondary | Best-effort support[^1][^8] | -| **Linux** | RHEL 7 | x86_64 | Secondary | Best-effort support[^2][^8] | -| **macOS** | 12.0+ (Monterey) | x86_64, ARM64 | Secondary | Best-effort support[^7] | -| **FreeBSD** | 13.0+ | x86_64, ARM64 | Secondary | pfSense/OPNsense ecosystem[^9] | - -**Testing Policy**: We test against the current and one previous major version of Windows and macOS to ensure compatibility with enterprise environments. macOS 14.0+ (Sonoma and later) are Primary support. - -### Process Enumeration - -- **Phase 1**: sysinfo crate for unified cross-platform baseline -- **Phase 2**: Platform-specific enhancements (eBPF, ETW, EndpointSecurity) -- **Phase 3**: Kernel-level real-time monitoring (Enterprise tier) -- **Fallback**: Graceful degradation when enhanced features unavailable - -### Kernel Monitoring (Enterprise Tier) - -- **Linux**: eBPF programs for real-time process and syscall monitoring -- **Windows**: ETW integration for kernel events and registry monitoring -- **macOS**: EndpointSecurity framework for process and file system events -- **Network**: Platform-specific network event correlation - -### Privilege Management - -- **Linux**: CAP_SYS_PTRACE, immediate capability dropping -- **Windows**: SeDebugPrivilege, token restriction after init -- **macOS**: Minimal entitlements, sandbox compatibility - -### Enterprise Security Features - -- **Authentication**: mTLS with certificate chain validation -- **Code Signing**: SLSA Level 3 provenance, Cosign signatures -- **Compliance**: NIST, ISO 27001, CIS framework mappings -- **Threat Intelligence**: STIX/TAXII integration, quarterly rule packs - -## Testing Strategy - -### Test Runner & Framework - -- **Test Runner**: cargo-nextest for faster, more reliable test execution -- **Async Testing**: tokio-test for async runtime testing utilities -- **CLI Testing**: insta for snapshot testing of CLI outputs and behavior -- **Integration Testing**: insta for snapshot testing and predicates for validation -- **Property Testing**: proptest for generative testing of edge cases and invariants - -### Testing Approach - -- **Unit Testing**: Algorithms and core logic only, minimal scope -- **Integration Testing**: Primary testing approach with minimal mocking for realistic scenarios -- **Property Testing**: proptest for generative testing of edge cases and invariants -- **Fuzz Testing**: Extensive fuzzing for security-critical components (SQL parser, config validation) -- **Performance Testing**: Criterion benchmarks with regression detection and CI integration - -### Coverage & Quality - -- **Target Coverage**: >85% code coverage across the codebase -- **Coverage Tools**: llvm-cov for coverage measurement and reporting -- **Snapshot Testing**: insta for deterministic CLI output validation -- **CI Matrix**: Test across Linux, macOS, Windows with multiple Rust versions (stable, beta, MSRV) - -[^5]: Windows 10: EOL October 14, 2025. Organizations should plan migration to Windows 11. - -[^6]: Windows Server 2019: EOL January 9, 2029. Consider upgrading to Windows Server 2022. - -[^1]: Ubuntu 18.04 (EOL April 2023): Legacy support for long-lived server deployments. Limited testing and no guaranteed compatibility. - -[^8]: **Enterprise Tier**: No eBPF kernel monitoring (requires kernel 5.4+). Graceful degradation to userspace monitoring with reduced threat detection capabilities. - -[^2]: RHEL 7 (EOL June 2024): Enterprise legacy support for organizations with extended support contracts. Compatibility not guaranteed. - -[^7]: macOS 12.0 (Monterey): EOL September 16, 2024. Legacy support for organizations with older Mac hardware. **Enterprise Tier**: Limited EndpointSecurity framework features compared to macOS 14.0+. Reduced code signing bypass detection and advanced threat monitoring capabilities. - -[^9]: **FreeBSD 13.0+**: pfSense/OPNsense ecosystem support. **Enterprise Tier**: No eBPF kernel monitoring (FreeBSD uses classic BPF). Full process and network monitoring via sysinfo crate and FreeBSD audit system. From f8104b8a6d281489f7d283438a15d72dcb4f8649 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Sun, 26 Apr 2026 11:11:05 -0400 Subject: [PATCH 03/11] docs(security): remove Enterprise Tier subsection from root SECURITY.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Advanced Security Features (Enterprise Tier)" subsection in SECURITY.md enumerated paid-tier features (mTLS for fleet aggregation, SLSA Level 3, Cosign) inside an OSS-repo policy doc. Per the open-core hygiene workflow, that's a violation — the OSS repo should not enumerate paid-tier specifics. Reframed the section as "Planned Hardening (Community Tier)" containing only items that are actually planned for the OSS Community tier: Merkle inclusion proofs (in progress), Cosign signatures, sandboxed execution, query whitelist. Added a single boundary footnote acknowledging that fleet-level mTLS between host agents and upstream aggregators belongs to commercial tiers, not this repo. The canonical security overview lives in Confluence pages 1802346 / 1802364 (DaemonEye Security Design Overview). Signed-off-by: UncleSp1d3r --- SECURITY.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index af1bd548..2025cf54 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -39,14 +39,15 @@ DaemonEye implements a **three-component security architecture** with strict pri - **Attack Surface Minimization**: No network listening, outbound-only connections - **Audit Trail**: BLAKE3 hash-chained audit ledger [Implemented]; Certificate Transparency-style Merkle tree inclusion proofs \[In Progress — stub returns empty vec in `crypto.rs`\] -### Advanced Security Features (Enterprise Tier) +### Planned Hardening (Community Tier) -- **mTLS Authentication**: Certificate chain validation for enterprise components [Planned] -- **Code Signing**: SLSA Level 3 provenance, Cosign signatures [Planned] - **Cryptographic Integrity**: Merkle tree with inclusion proofs and periodic checkpoints [In Progress — chain hashing implemented; inclusion proof generation stubbed] +- **Code Signing**: SLSA Level 3 provenance, Cosign signatures [Planned] - **Sandboxed Execution**: Read-only database connections for detection engine [Planned] - **Query Whitelist**: Only SELECT statements with approved functions allowed [Implemented at rule load time; not yet enforced at execution time] +> Fleet-level transport security (mTLS between host agents and upstream aggregators) is provided by commercial tiers, sold separately, not in this repo. + ## Reporting a Vulnerability ### How to Report From 52d59f433d2ff7b5e760d15bd29efe5384c63604 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Sun, 26 Apr 2026 11:13:04 -0400 Subject: [PATCH 04/11] docs: trim residual paid-tier mentions in project-overview and security_design_overview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 7 of the open-core hygiene workflow — file-level deletion and top-level scrubs miss inline pollution. Remaining hits in OSS user- facing docs were tier-mapped Organizational Context lines and Cross-Platform Support entries that put "(Enterprise tier)" labels on kernel-collector capabilities the OSS repo does not provide. Edited: - docs/src/project-overview.md * Replaced the four-line tier-mapped Organizational Context table (Small Teams=Core, Consultancies=Business, Enterprises=Enterprise, Government/Military=airgapped) with a single boundary-acknowledgement paragraph describing which deployments this repo serves directly and which are commercial-tier responsibilities * Reframed Cross-Platform Support entries to describe the actual sysinfo-based collection that the OSS Community tier delivers, moving eBPF / ETW / EndpointSecurity to a single boundary footnote - docs/src/technical/security_design_overview.md * SC-36 (Distributed Processing and Storage) — replaced the "federated security centers, distributed data storage, and secure inter-node communication" implementation note with a boundary footnote pointing at commercial tiers Final grep sweep confirms all remaining "tier" mentions in tracked OSS docs are boundary footnotes (the preferred pattern from the hygiene workflow), not paid-tier feature claims. Signed-off-by: UncleSp1d3r --- docs/src/project-overview.md | 14 ++++++-------- docs/src/technical/security_design_overview.md | 2 +- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/src/project-overview.md b/docs/src/project-overview.md index e5107760..35bdbbbf 100644 --- a/docs/src/project-overview.md +++ b/docs/src/project-overview.md @@ -96,10 +96,7 @@ DaemonEye implements a **three-component security architecture** with strict pri ### **Organizational Context** -- **Small Teams**: Core tier for basic process monitoring -- **Consultancies**: Business tier for client management and reporting -- **Enterprises**: Enterprise tier for large-scale, federated deployments -- **Government/Military**: Airgapped environments with strict compliance requirements +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 @@ -137,10 +134,11 @@ DaemonEye implements a **three-component security architecture** with strict pri #### Cross-Platform Support -- **Linux**: Native process enumeration with eBPF integration (Enterprise tier) -- **macOS**: EndpointSecurity framework integration (Enterprise tier) -- **Windows**: ETW integration and Windows API access (Enterprise tier) -- **Container Support**: Kubernetes DaemonSet deployment +- **Linux**: Native process enumeration via `sysinfo` and procfs +- **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 diff --git a/docs/src/technical/security_design_overview.md b/docs/src/technical/security_design_overview.md index 5556e9ac..914cdc75 100644 --- a/docs/src/technical/security_design_overview.md +++ b/docs/src/technical/security_design_overview.md @@ -1262,7 +1262,7 @@ Based on analysis of DaemonEye's current design against NIST SP 800-53 requireme - **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**: Include federated security centers, distributed data storage, and secure inter-node communication +- **Implementation Notes**: Distributed processing and multi-node aggregation are commercial-tier concerns, handled outside this repo. **SC-37 (Out-of-Band Channels)**: From 9a301a9acbfef511a0ae5587b430cce4a05b125e Mon Sep 17 00:00:00 2001 From: "dosubot[bot]" <131922026+dosubot[bot]@users.noreply.github.com> Date: Sun, 26 Apr 2026 15:17:29 +0000 Subject: [PATCH 05/11] docs: Dosu updates for PR #179 --- docs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index 6dea3028..8fd2961d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,15 +7,15 @@ This directory contains the comprehensive documentation for DaemonEye, built usi The documentation is organized into the following sections: - **Introduction**: Overview and getting started +- **Project Overview**: Detailed project information and value propositions - **Architecture**: System architecture and design principles - **Technical**: Technical specifications and implementation details -- **User Guides**: Comprehensive user and operator guides -- **API Reference**: Complete API documentation -- **Deployment**: Installation and deployment guides - **Security**: Security considerations and best practices - **Testing**: Testing strategies and guidelines - **Contributing**: Contribution guidelines and development setup +User Guides, API Reference, and Deployment documentation will be published with the v1.0.0 release. + ## Building the Documentation ### Prerequisites From 9eebbc1a3a105f86c99cec0375f71ea4a89d1995 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Thu, 30 Apr 2026 00:22:44 -0400 Subject: [PATCH 06/11] chore(config): update language server list and clean up tool documentation Signed-off-by: UncleSp1d3r --- .serena/project.yml | 81 +++++++++++++++------------------------------ 1 file changed, 27 insertions(+), 54 deletions(-) diff --git a/.serena/project.yml b/.serena/project.yml index 22273f42..461581d2 100644 --- a/.serena/project.yml +++ b/.serena/project.yml @@ -1,15 +1,16 @@ - - # list of languages for which language servers are started; choose from: -# al bash clojure cpp csharp -# csharp_omnisharp dart elixir elm erlang -# fortran fsharp go groovy haskell -# java julia kotlin lua markdown -# matlab nix pascal perl php -# php_phpactor powershell python python_jedi r -# rego ruby ruby_solargraph rust scala -# swift terraform toml typescript typescript_vts -# vue yaml zig +# al ansible bash clojure cpp +# cpp_ccls crystal csharp csharp_omnisharp dart +# elixir elm erlang fortran fsharp +# go groovy haskell haxe hlsl +# java json julia kotlin lean4 +# lua luau markdown matlab msl +# nix ocaml pascal perl php +# php_phpactor powershell python python_jedi python_ty +# r rego ruby ruby_solargraph rust +# scala solidity swift systemverilog terraform +# toml typescript typescript_vts vue yaml +# zig # (This list may be outdated. For the current list, see values of Language enum here: # https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py # For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.) @@ -24,7 +25,7 @@ # The first language is the default language and the respective language server will be used as a fallback. # Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored. languages: -- rust + - rust # the encoding used by text files in the project # For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings @@ -45,45 +46,7 @@ read_only: false # list of tool names to exclude. # This extends the existing exclusions (e.g. from the global configuration) -# -# Below is the complete list of tools for convenience. -# To make sure you have the latest list of tools, and to view their descriptions, -# execute `uv run scripts/print_tool_overview.py`. -# -# * `activate_project`: Activates a project by name. -# * `check_onboarding_performed`: Checks whether project onboarding was already performed. -# * `create_text_file`: Creates/overwrites a file in the project directory. -# * `delete_lines`: Deletes a range of lines within a file. -# * `delete_memory`: Deletes a memory from Serena's project-specific memory store. -# * `execute_shell_command`: Executes a shell command. -# * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced. -# * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type). -# * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type). -# * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes. -# * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file. -# * `initial_instructions`: Gets the initial instructions for the current project. -# Should only be used in settings where the system prompt cannot be set, -# e.g. in clients you have no control over, like Claude Desktop. -# * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. -# * `insert_at_line`: Inserts content at a given line in a file. -# * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. -# * `list_dir`: Lists files and directories in the given directory (optionally with recursion). -# * `list_memories`: Lists memories in Serena's project-specific memory store. -# * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). -# * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context). -# * `read_file`: Reads a file within the project directory. -# * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. -# * `remove_project`: Removes a project from the Serena configuration. -# * `replace_lines`: Replaces a range of lines within a file with new content. -# * `replace_symbol_body`: Replaces the full definition of a symbol. -# * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen. -# * `search_for_pattern`: Performs a search for a pattern in the project. -# * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase. -# * `switch_modes`: Activates modes by providing a list of their names -# * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information. -# * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task. -# * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed. -# * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store. +# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html excluded_tools: [] # initial prompt for the project. It will always be given to the LLM upon activating the project @@ -94,10 +57,12 @@ project_name: "daemoneye" # list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default). # This extends the existing inclusions (e.g. from the global configuration). +# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html included_optional_tools: [] # fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools. # This cannot be combined with non-empty excluded_tools or included_optional_tools. +# Find the list of tools here: https://oraios.github.io/serena/01-about/035_tools.html fixed_tools: [] # list of mode names to that are always to be included in the set of active modes @@ -108,11 +73,14 @@ fixed_tools: [] # Set this to a list of mode names to always include the respective modes for this project. base_modes: -# list of mode names that are to be activated by default. -# The full set of modes to be activated is base_modes + default_modes. -# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply. +# list of mode names that are to be activated by default, overriding the setting in the global configuration. +# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes. +# If the setting is undefined/empty, the default_modes from the global configuration (serena_config.yml) apply. # Otherwise, this overrides the setting from the global configuration (serena_config.yml). +# Therefore, you can set this to [] if you do not want the default modes defined in the global config to apply +# for this project. # This setting can, in turn, be overridden by CLI parameters (--mode). +# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes default_modes: # time budget (seconds) per tool call for the retrieval of additional symbol information @@ -150,3 +118,8 @@ ignored_memory_patterns: [] # Have a look at the docstring of the constructors of the LS implementations within solidlsp (e.g., for C# or PHP) to see which options are available. # No documentation on options means no options are available. ls_specific_settings: {} + +# list of mode names to be activated additionally for this project, e.g. ["query-projects"] +# The full set of modes to be activated is base_modes (from global config) + default_modes + added_modes. +# See https://oraios.github.io/serena/02-usage/050_configuration.html#modes +added_modes: From dfd41f90a9e42c12f944d224226f34e3469e1cb1 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Thu, 30 Apr 2026 00:22:55 -0400 Subject: [PATCH 07/11] chore(docs): update README and .gitignore for clarity and consistency Signed-off-by: UncleSp1d3r --- .gitignore | 1 + README.md | 45 ++++++------- mise.lock | 192 ++++++++++++++++++++++++++--------------------------- mise.toml | 6 +- 4 files changed, 122 insertions(+), 122 deletions(-) diff --git a/.gitignore b/.gitignore index fa02db41..7fce066e 100644 --- a/.gitignore +++ b/.gitignore @@ -142,3 +142,4 @@ docs/plans **/*.local.* .context/ todos/ +.claude/ diff --git a/README.md b/README.md index 32b35741..62f42daa 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ # DaemonEye -Security-focused, high-performance process monitoring — implemented in Rust. - -Badges: CI, coverage, and maintainability are configured in the repo. See the badges at the top of this file when viewed on GitHub. +Security-focused process monitoring, written in Rust. ## Overview -DaemonEye is a Rust workspace with multiple components for collecting process information, orchestrating detections, and interacting via a CLI. The repository contains: +DaemonEye is a Rust workspace that collects process information, runs detections against it, and exposes the results through a CLI. The repository contains: - **procmond**: Privileged process monitoring daemon built on collector-core framework (binary + library) - **daemoneye-agent**: User-space orchestrator with embedded EventBus broker and RPC service (binary) @@ -15,7 +13,7 @@ DaemonEye is a Rust workspace with multiple components for collecting process in - **collector-core**: Extensible collection framework with EventSource trait (library) - **daemoneye-eventbus**: Cross-platform IPC event bus with embedded broker and RPC patterns (library) -Security and reliability are emphasized via strict linting, no unsafe code, and comprehensive tests and benches. +The workspace forbids unsafe code, treats clippy warnings as errors, and is covered by unit, property, and snapshot tests plus criterion benchmarks. ## Technology stack @@ -63,11 +61,11 @@ DaemonEye/ - Windows: `just setup && just install-tools` - Unix: `just setup && just install-tools` -If you don’t use just, you can run the equivalent cargo commands shown below. +If you don't use just, the equivalent cargo commands are listed below. ## Commit signing -The workspace enables mandatory signed commits and a rebase-first sync strategy via VS Code settings. Follow the step-by-step instructions in [`docs/src/contributing.md`](docs/src/contributing.md#commit-signing-and-gpg-setup) to configure GPG, export your public key, and set up git before contributing. +The workspace requires signed commits and uses a rebase-first sync strategy (configured via VS Code settings). See [`docs/src/contributing.md`](docs/src/contributing.md#commit-signing-and-gpg-setup) for GPG and git setup before contributing. ## Build and run @@ -119,7 +117,7 @@ Collector-specific environment overrides (used by collector-core) are additional Agent-specific environment toggle (used in tests/dev): -- DAEMONEYE_AGENT_TEST_MODE=1 — enables test mode paths in the agent +- DAEMONEYE_AGENT_TEST_MODE=1: enables test mode paths in the agent Default configuration values are defined in code. See daemoneye-lib/src/config.rs and collector-core/src/config.rs for details and additional fields (database path, logging level/format, alert sinks, etc.). @@ -154,25 +152,24 @@ Benchmarks use criterion. Run via `just bench` or `cargo bench`. Summary of notable env vars: -- PROCMOND\_\* / DAEMONEYE_AGENT\_\* / DAEMONEYE_CLI\_\* — general config via Figment (use `__` for nested keys) -- PROCMOND_COLLECTOR_MAX_EVENT_SOURCES, PROCMOND_COLLECTOR_EVENT_BUFFER_SIZE, PROCMOND_COLLECTOR_ENABLE_TELEMETRY, PROCMOND_COLLECTOR_DEBUG_LOGGING — collector-core overrides -- DAEMONEYE_AGENT_TEST_MODE — agent test mode +- PROCMOND\_\* / DAEMONEYE_AGENT\_\* / DAEMONEYE_CLI\_\*: general config via Figment (use `__` for nested keys) +- PROCMOND_COLLECTOR_MAX_EVENT_SOURCES, PROCMOND_COLLECTOR_EVENT_BUFFER_SIZE, PROCMOND_COLLECTOR_ENABLE_TELEMETRY, PROCMOND_COLLECTOR_DEBUG_LOGGING: collector-core overrides +- DAEMONEYE_AGENT_TEST_MODE: agent test mode Additional OS/environment variables may be referenced in tests for compatibility checks (e.g., HOSTNAME, USER, OS), but they are not required for normal operation. ## Platform notes -- **Unix**: IPC is provided via Unix domain sockets using interprocess crate with protobuf messaging -- **Windows**: IPC uses named pipes through interprocess crate with protobuf messaging -- **Event Bus**: daemoneye-eventbus provides local IPC pub/sub messaging between collectors and agent on the same system with hierarchical topic routing and correlation metadata -- **Embedded Broker**: daemoneye-agent runs an embedded EventBus broker for local collector coordination with support for workflow tracking and forensic analysis -- **RPC Services**: Collector lifecycle management (start/stop/restart/health checks) via RPC patterns over the EventBus with timeout handling and correlation tracking -- **Multi-Collector Coordination**: Topic-based task distribution and result aggregation across multiple collector types with capability-based routing +- **Unix**: IPC over Unix domain sockets via the `interprocess` crate, using protobuf messages. +- **Windows**: IPC over named pipes via the `interprocess` crate, using protobuf messages. +- **Event bus**: `daemoneye-eventbus` is local-only pub/sub between collectors and the agent on the same host. Topics are hierarchical and messages carry correlation metadata. +- **Embedded broker**: `daemoneye-agent` runs the EventBus broker in-process. Workflow tracking and forensic correlation are built on top of it. +- **RPC services**: Collector lifecycle (start, stop, restart, health checks) is exposed over RPC on the bus with request timeouts and correlation IDs. +- **Multi-collector coordination**: Tasks are distributed by topic and routed by collector capability; results are aggregated across collector types. ## Documentation -- Docs sources live under ./docs (mdBook). Building locally: `just docs-install` then `mdbook build docs`. -- Some deep links in older README versions may not exist yet. TODO: Audit and update docs links once the book structure stabilizes. +- Docs sources live under ./docs (mdBook). Build locally with `just docs-install` then `mdbook build docs`. ## License @@ -180,8 +177,10 @@ Apache License 2.0. See LICENSE for full text. ## Roadmap and status -This README reflects the current repository configuration (workspace crates, tasks, and configs). Some features described in earlier drafts (e.g., certain alerting sinks or centralized management) may be in-progress. +This README describes what is in the repository today (workspace crates, justfile tasks, configuration surface). Several features in the spec, including some alerting sinks and centralized management, are not yet implemented. + +Open items for this README: -- TODO: Document concrete command-line flags for each binary (once stabilized) -- TODO: Add end-to-end quickstart with example config and sample output -- TODO: Publish prebuilt binaries via GoReleaser and link here +- Document the concrete command-line flags for each binary once they stabilize. +- Add an end-to-end quickstart with an example config and sample output. +- Publish prebuilt binaries via GoReleaser and link them here. diff --git a/mise.lock b/mise.lock index 04730511..0a5da1f9 100644 --- a/mise.lock +++ b/mise.lock @@ -1,4 +1,4 @@ -# @generated - this file is auto-generated by `mise lock` https://mise.jdx.dev/dev-tools/mise-lock.html +# @generated - this file is auto-generated by `mise lock` https://mise.en.dev/dev-tools/mise-lock.html [[tools.actionlint]] version = "1.7.12" @@ -60,52 +60,52 @@ url = "https://github.com/rhysd/actionlint/releases/download/v1.7.12/actionlint_ provenance = "github-attestations" [[tools.bun]] -version = "1.3.12" +version = "1.3.13" backend = "core:bun" [tools.bun."platforms.linux-arm64"] -checksum = "sha256:c40bc0ebca11bde7d75af497a654a874d0c7fd8d6a8d6031c173c10c9064297b" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-linux-aarch64.zip" +checksum = "sha256:70bae41b3908b0a120e1e58c5c8af30e74afae3b8d11b0d3fdd8e787ddfb4b22" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-linux-aarch64.zip" [tools.bun."platforms.linux-arm64-musl"] -checksum = "sha256:731baab945bc471c17248ea375e66f71442879d2595c54045b3e861f4e8b9ab1" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-linux-aarch64-musl.zip" +checksum = "sha256:5385e978107ce4934298d8d6afe9bfbb898683f6cc23e6753a0da60bc60c5b81" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-linux-aarch64-musl.zip" [tools.bun."platforms.linux-x64"] -checksum = "sha256:11dc3ee11bc1695e149737c6ca3d5619302cf4346e6b8a6ec7988967ef01ddc5" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-linux-x64.zip" +checksum = "sha256:79c0771fa8b92c33aae41e15a0e0d307ea99d0e2f00317c71c6c53237a78e25a" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-linux-x64.zip" [tools.bun."platforms.linux-x64-baseline"] -checksum = "sha256:f8bb377a9ae93d44697ff91a2611164d2aedc9263415d623b0c3af24a6f55dab" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-linux-x64-baseline.zip" +checksum = "sha256:9d8a24292a7068090205daac0a5a223f5f69736f5287e37bf88d3b4031edc750" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-linux-x64-baseline.zip" [tools.bun."platforms.linux-x64-musl"] -checksum = "sha256:5a9f9a2102d4bd0d5210b4f6bd345151d2310623947085177c1b306e8587dce6" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-linux-x64-musl.zip" +checksum = "sha256:5b91a48f0b00df9fd2da8bff1a795d2659d842da966432969203f25da19d1c74" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-linux-x64-musl.zip" [tools.bun."platforms.linux-x64-musl-baseline"] -checksum = "sha256:a95e079aef96f1387b86e27b69f9a6babbd08154d9a59483f29d9de285b8e3ad" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-linux-x64-musl-baseline.zip" +checksum = "sha256:88ca7c7ad235b498f549eea2f770f434e9f0f5e9ba95168a2d3a1f235184c394" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-linux-x64-musl-baseline.zip" [tools.bun."platforms.macos-arm64"] -checksum = "sha256:6c4bb87dd013ed1a8d6a16e357a3d094959fd5530b4d7061f7f3680c3c7cea1c" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-darwin-aarch64.zip" +checksum = "sha256:5467e3f65dba526b9fea98f0cce04efafc0c63e169733ec27b876a3ad32da190" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-darwin-aarch64.zip" [tools.bun."platforms.macos-x64"] -checksum = "sha256:0f58c53a3e7947f1e626d2f8d285f97c14b7cadcca9c09ebafc0ae9d35b58c3d" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-darwin-x64.zip" +checksum = "sha256:e5a6c8b64f419925232d111ecb13e25f0abf55e54f792341f987623fd0778009" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-darwin-x64.zip" [tools.bun."platforms.macos-x64-baseline"] -checksum = "sha256:cc4e22130c2bc2d944d3a286de08f2ed37fa74136e59760f3a4661e610246474" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-darwin-x64-baseline.zip" +checksum = "sha256:a98ba6a480f22fda9b343626b906a4e26aa53618bf85d2bc5928ecf2ba45f0ed" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-darwin-x64-baseline.zip" [tools.bun."platforms.windows-x64"] -checksum = "sha256:841ff9c5dffcaa3a2620d1e3f87ee500f32a4ca830b001cade7a3479609d4a89" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-windows-x64.zip" +checksum = "sha256:85b14f3e0584218e9b63407b3aa6b90c4835ec5c32435c1f12cb6fc13667c7c9" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-windows-x64.zip" [tools.bun."platforms.windows-x64-baseline"] -checksum = "sha256:2d3d5f88a95943563f56f3643c8f4e2422261018f6d915329bb2fb33f7256ba2" -url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.12/bun-windows-x64-baseline.zip" +checksum = "sha256:c68c7903c1190101590cc1b2129835f47211b3b37ae87759f2b97d6534aa3ad1" +url = "https://github.com/oven-sh/bun/releases/download/bun-v1.3.13/bun-windows-x64-baseline.zip" [[tools.cargo-binstall]] version = "1.18.1" @@ -228,7 +228,7 @@ version = "1.1.2" backend = "cargo:cargo-release" [[tools."cargo:cargo-zigbuild"]] -version = "0.22.2" +version = "0.22.3" backend = "cargo:cargo-zigbuild" [[tools."cargo:mdbook"]] @@ -323,52 +323,52 @@ url = "https://github.com/goreleaser/goreleaser/releases/download/v2.15.3/gorele provenance = "github-attestations" [[tools.just]] -version = "1.49.0" +version = "1.50.0" backend = "aqua:casey/just" [tools.just."platforms.linux-arm64"] -checksum = "sha256:993b78f51004248114af22368f69715541542b3c9941c80e02f8ae10eb404ae0" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-aarch64-unknown-linux-musl.tar.gz" +checksum = "sha256:3beb4967ce05883cf09ac12d6d128166eb4c6d0b03eff74b61018a6880655d7d" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-aarch64-unknown-linux-musl.tar.gz" [tools.just."platforms.linux-arm64-musl"] -checksum = "sha256:993b78f51004248114af22368f69715541542b3c9941c80e02f8ae10eb404ae0" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-aarch64-unknown-linux-musl.tar.gz" +checksum = "sha256:3beb4967ce05883cf09ac12d6d128166eb4c6d0b03eff74b61018a6880655d7d" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-aarch64-unknown-linux-musl.tar.gz" [tools.just."platforms.linux-x64"] -checksum = "sha256:05eb2f068b641b06e5b318796c2e27d4dcca608e65b34329a08c1b9f582611bd" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-unknown-linux-musl.tar.gz" +checksum = "sha256:27e011cd6328fadd632e59233d2cf5f18460b8a8c4269acd324c1a8669f34db0" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-unknown-linux-musl.tar.gz" [tools.just."platforms.linux-x64-baseline"] -checksum = "sha256:05eb2f068b641b06e5b318796c2e27d4dcca608e65b34329a08c1b9f582611bd" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-unknown-linux-musl.tar.gz" +checksum = "sha256:27e011cd6328fadd632e59233d2cf5f18460b8a8c4269acd324c1a8669f34db0" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-unknown-linux-musl.tar.gz" [tools.just."platforms.linux-x64-musl"] -checksum = "sha256:05eb2f068b641b06e5b318796c2e27d4dcca608e65b34329a08c1b9f582611bd" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-unknown-linux-musl.tar.gz" +checksum = "sha256:27e011cd6328fadd632e59233d2cf5f18460b8a8c4269acd324c1a8669f34db0" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-unknown-linux-musl.tar.gz" [tools.just."platforms.linux-x64-musl-baseline"] -checksum = "sha256:05eb2f068b641b06e5b318796c2e27d4dcca608e65b34329a08c1b9f582611bd" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-unknown-linux-musl.tar.gz" +checksum = "sha256:27e011cd6328fadd632e59233d2cf5f18460b8a8c4269acd324c1a8669f34db0" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-unknown-linux-musl.tar.gz" [tools.just."platforms.macos-arm64"] -checksum = "sha256:d21b20df01ec9b9762b0ef08e56ae8dccf3738770edeafa8d2b3a750aee06d78" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-aarch64-apple-darwin.tar.gz" +checksum = "sha256:891262207663bff1aa422dbe799a76deae4064eaa445f14eb28aef7a388222cd" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-aarch64-apple-darwin.tar.gz" [tools.just."platforms.macos-x64"] -checksum = "sha256:e0b83a9352952ab25e5cf13f6cb03dd1872416e5d89388b56d6ca58f11b0a3a8" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-apple-darwin.tar.gz" +checksum = "sha256:e4fa28fe63381ca32fad101e86d4a1da7cd2d34d1b080985a37ec9dc951922fe" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-apple-darwin.tar.gz" [tools.just."platforms.macos-x64-baseline"] -checksum = "sha256:e0b83a9352952ab25e5cf13f6cb03dd1872416e5d89388b56d6ca58f11b0a3a8" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-apple-darwin.tar.gz" +checksum = "sha256:e4fa28fe63381ca32fad101e86d4a1da7cd2d34d1b080985a37ec9dc951922fe" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-apple-darwin.tar.gz" [tools.just."platforms.windows-x64"] -checksum = "sha256:657338772efd17a31d67285bb5ed691da87741e44311c0366273c6cb7d913b15" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-pc-windows-msvc.zip" +checksum = "sha256:5dc713f049e174e22de41fd06292a26c9b90f2d37c1be9390d2082fe6928b376" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-pc-windows-msvc.zip" [tools.just."platforms.windows-x64-baseline"] -checksum = "sha256:657338772efd17a31d67285bb5ed691da87741e44311c0366273c6cb7d913b15" -url = "https://github.com/casey/just/releases/download/1.49.0/just-1.49.0-x86_64-pc-windows-msvc.zip" +checksum = "sha256:5dc713f049e174e22de41fd06292a26c9b90f2d37c1be9390d2082fe6928b376" +url = "https://github.com/casey/just/releases/download/1.50.0/just-1.50.0-x86_64-pc-windows-msvc.zip" [[tools.lychee]] version = "0.23.0" @@ -411,7 +411,7 @@ checksum = "sha256:0fda7ff0a60c0250939fc25361c2d4e6e7853c31c996733fdd5a1dd760bcb url = "https://github.com/lycheeverse/lychee/releases/download/lychee-v0.23.0/lychee-x86_64-windows.exe" [[tools.markdownlint-cli2]] -version = "0.22.0" +version = "0.22.1" backend = "npm:markdownlint-cli2" [[tools."pipx:mdformat"]] @@ -422,7 +422,7 @@ backend = "pipx:mdformat" uvx_args = "--with mdformat-gfm --with mdformat-config --with mdformat-footnote --with mdformat-front-matters --with mdformat-simple-breaks --with mdformat-web --with mdformat-gfm-alerts --with mdformat-toc" [[tools."pipx:pre-commit"]] -version = "4.5.1" +version = "4.6.0" backend = "pipx:pre-commit" [[tools.prettier]] @@ -430,100 +430,100 @@ version = "3.8.3" backend = "npm:prettier" [[tools.protobuf]] -version = "34.0" +version = "34.1" backend = "aqua:protocolbuffers/protobuf/protoc" [tools.protobuf."platforms.linux-arm64"] -checksum = "sha256:f0b8aad28be5ea6150c082f96ac57e028154afb9ee29f4ce092b5a39df8ae6c8" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-aarch_64.zip" +checksum = "sha256:31c5e9e3c7bf013cf41fb97765ee255c140024a6b175b6cc9b64beddd7c23ba7" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-aarch_64.zip" [tools.protobuf."platforms.linux-arm64-musl"] -checksum = "sha256:f0b8aad28be5ea6150c082f96ac57e028154afb9ee29f4ce092b5a39df8ae6c8" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-aarch_64.zip" +checksum = "sha256:31c5e9e3c7bf013cf41fb97765ee255c140024a6b175b6cc9b64beddd7c23ba7" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-aarch_64.zip" [tools.protobuf."platforms.linux-x64"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protobuf."platforms.linux-x64-baseline"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protobuf."platforms.linux-x64-musl"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protobuf."platforms.linux-x64-musl-baseline"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protobuf."platforms.macos-arm64"] -checksum = "sha256:3ef35187a3c8aed81ee57e792227e483e558fa56c93fce525e569bff55794c1a" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-osx-aarch_64.zip" +checksum = "sha256:2c7e92b8b578916937df132b3032e2e8e6c170862ecf7a8333094a6f3d03650c" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-osx-aarch_64.zip" [tools.protobuf."platforms.macos-x64"] -checksum = "sha256:d58fcd413a9ed458283d54023e409fd5cf767da4ed225d1ffaffd83cf2764f53" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-osx-x86_64.zip" +checksum = "sha256:ab124429c1f49951f03b6c0c0e911fec04e2c7c20de5c935e0cde7353bbd016c" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-osx-x86_64.zip" [tools.protobuf."platforms.macos-x64-baseline"] -checksum = "sha256:d58fcd413a9ed458283d54023e409fd5cf767da4ed225d1ffaffd83cf2764f53" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-osx-x86_64.zip" +checksum = "sha256:ab124429c1f49951f03b6c0c0e911fec04e2c7c20de5c935e0cde7353bbd016c" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-osx-x86_64.zip" [tools.protobuf."platforms.windows-x64"] -checksum = "sha256:76ddeb5ae7a31c8f9f7759d3b843a4cadda2150ac037ad0c1794665d6cf31fce" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-win64.zip" +checksum = "sha256:6d7ebdc75e9c1f0026d4fb28f17ef1d0aae77d36744d83a9e052d79ba493724f" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-win64.zip" [tools.protobuf."platforms.windows-x64-baseline"] -checksum = "sha256:76ddeb5ae7a31c8f9f7759d3b843a4cadda2150ac037ad0c1794665d6cf31fce" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-win64.zip" +checksum = "sha256:6d7ebdc75e9c1f0026d4fb28f17ef1d0aae77d36744d83a9e052d79ba493724f" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-win64.zip" [[tools.protoc]] -version = "34.0" +version = "34.1" backend = "aqua:protocolbuffers/protobuf/protoc" [tools.protoc."platforms.linux-arm64"] -checksum = "sha256:f0b8aad28be5ea6150c082f96ac57e028154afb9ee29f4ce092b5a39df8ae6c8" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-aarch_64.zip" +checksum = "sha256:31c5e9e3c7bf013cf41fb97765ee255c140024a6b175b6cc9b64beddd7c23ba7" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-aarch_64.zip" [tools.protoc."platforms.linux-arm64-musl"] -checksum = "sha256:f0b8aad28be5ea6150c082f96ac57e028154afb9ee29f4ce092b5a39df8ae6c8" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-aarch_64.zip" +checksum = "sha256:31c5e9e3c7bf013cf41fb97765ee255c140024a6b175b6cc9b64beddd7c23ba7" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-aarch_64.zip" [tools.protoc."platforms.linux-x64"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protoc."platforms.linux-x64-baseline"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protoc."platforms.linux-x64-musl"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protoc."platforms.linux-x64-musl-baseline"] -checksum = "sha256:e9a91b6fcfe4177ec2cd35fc8f15c1e811fa0ecdef9372755cd6d3513d5faaab" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-linux-x86_64.zip" +checksum = "sha256:af27ea66cd26938fe48587804ca7d4817457a08350021a1c6e23a27ccc8c6904" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-linux-x86_64.zip" [tools.protoc."platforms.macos-arm64"] -checksum = "sha256:3ef35187a3c8aed81ee57e792227e483e558fa56c93fce525e569bff55794c1a" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-osx-aarch_64.zip" +checksum = "sha256:2c7e92b8b578916937df132b3032e2e8e6c170862ecf7a8333094a6f3d03650c" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-osx-aarch_64.zip" [tools.protoc."platforms.macos-x64"] -checksum = "sha256:d58fcd413a9ed458283d54023e409fd5cf767da4ed225d1ffaffd83cf2764f53" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-osx-x86_64.zip" +checksum = "sha256:ab124429c1f49951f03b6c0c0e911fec04e2c7c20de5c935e0cde7353bbd016c" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-osx-x86_64.zip" [tools.protoc."platforms.macos-x64-baseline"] -checksum = "sha256:d58fcd413a9ed458283d54023e409fd5cf767da4ed225d1ffaffd83cf2764f53" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-osx-x86_64.zip" +checksum = "sha256:ab124429c1f49951f03b6c0c0e911fec04e2c7c20de5c935e0cde7353bbd016c" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-osx-x86_64.zip" [tools.protoc."platforms.windows-x64"] -checksum = "sha256:76ddeb5ae7a31c8f9f7759d3b843a4cadda2150ac037ad0c1794665d6cf31fce" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-win64.zip" +checksum = "sha256:6d7ebdc75e9c1f0026d4fb28f17ef1d0aae77d36744d83a9e052d79ba493724f" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-win64.zip" [tools.protoc."platforms.windows-x64-baseline"] -checksum = "sha256:76ddeb5ae7a31c8f9f7759d3b843a4cadda2150ac037ad0c1794665d6cf31fce" -url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.0/protoc-34.0-win64.zip" +checksum = "sha256:6d7ebdc75e9c1f0026d4fb28f17ef1d0aae77d36744d83a9e052d79ba493724f" +url = "https://github.com/protocolbuffers/protobuf/releases/download/v34.1/protoc-34.1-win64.zip" [[tools.python]] version = "3.14.4" diff --git a/mise.toml b/mise.toml index 49e8905b..cb2cb53a 100644 --- a/mise.toml +++ b/mise.toml @@ -25,9 +25,9 @@ rust = { version = "1.95.0", components = "llvm-tools,car prettier = "3.8.3" actionlint = "1.7.12" lychee = "0.23.0" -markdownlint-cli2 = "0.22.0" -protobuf = "34.0" -protoc = "34.0" +markdownlint-cli2 = "0.22.1" +protobuf = "34.1" +protoc = "34.1" zig = "latest" "cargo:cargo-zigbuild" = "latest" bun = "latest" From aac8ee0756d12ae7e1c43e3a3f2bbb68ac57f74d Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Thu, 30 Apr 2026 00:50:17 -0400 Subject: [PATCH 08/11] chore(justfile): normalize boolean set directives `just --fmt` prefers the bare `set X` form over `set X := true` for boolean defaults. Re-running the formatter against the working tree brings the file back into the format the lint check enforces. This unblocks `just lint-justfile` (and `just ci-check` by extension), which was failing on this drift independently of any other work on the branch. Signed-off-by: UncleSp1d3r --- justfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/justfile b/justfile index 587b2e30..bc872fdf 100644 --- a/justfile +++ b/justfile @@ -3,8 +3,8 @@ set shell := ["bash", "-cu"] set windows-shell := ["powershell", "-NoProfile", "-Command"] -set dotenv-load := true -set ignore-comments := true +set dotenv-load +set ignore-comments # Use mise to manage all dev tools (go, pre-commit, uv, etc.) # See mise.toml for tool versions From a2ca52b58d072f4a7820491dcd1d4df9413ff4c4 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Thu, 30 Apr 2026 00:50:33 -0400 Subject: [PATCH 09/11] docs(security): humanize SECURITY.md prose Rewrite the SECURITY.md content to drop AI-flavored writing patterns that had crept in: circular bullet labels (Defense in Depth: multiple security layers...), generic platitudes in For Users / For Developers, em-dash overuse, the "Note:" hedge, and the "three-component" claim that mismatched the four-bullet component list. Replace circular descriptions with concrete project-specific behavior (procmond/agent/cli ledger access, BLAKE3 chain, IPC framing, audit ledger review steps, CI advisory enforcement). Drop the duplicate If Accepted / If Declined block that restated the response timeline. No policy or contact details changed - all email, PGP, GitHub advisory, and resolution-timeline information is preserved. Signed-off-by: UncleSp1d3r --- SECURITY.md | 124 ++++++++++++++++++++++------------------------------ 1 file changed, 52 insertions(+), 72 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 2025cf54..c31b48fe 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -9,42 +9,41 @@ DaemonEye follows semantic versioning (SemVer) with security updates provided fo | 0.1.x | :white_check_mark: | Current development version | | < 0.1 | :x: | Pre-release versions not supported | -**Note**: As DaemonEye is currently in pre-1.0 development, we focus security updates on the latest 0.1.x series. Once we reach 1.0, we will support the current major version and one previous major version. +DaemonEye is in pre-1.0 development, so security updates target the latest 0.1.x series. After 1.0, we will support the current major version and one previous major version. ## Security Architecture -DaemonEye implements a **three-component security architecture** with strict privilege separation: +DaemonEye is split into three binaries with strict privilege separation, plus a shared library: -- **procmond**: Privileged process collector with minimal attack surface -- **daemoneye-agent**: User-space orchestrator for detection and alerting -- **daemoneye-cli**: Command-line interface for operators -- **daemoneye-lib**: Shared library providing core functionality +- **procmond**: privileged process collector. Runs elevated only as long as it needs to. +- **daemoneye-agent**: user-space orchestrator for detection and alert delivery. +- **daemoneye-cli**: read-only operator interface. +- **daemoneye-lib**: shared library (config, models, storage, detection, crypto). No direct privileges of its own. ### Security Principles -- **Principle of Least Privilege**: Components run with minimal required permissions -- **Privilege Separation**: Only procmond runs with elevated privileges when necessary -- **Defense in Depth**: Multiple security layers and validation points -- **Zero Trust**: No implicit trust between components or external systems -- **Audit Trail**: Certificate Transparency-style Merkle tree with cryptographic integrity +- **Least privilege**: Components run with the minimum permissions they need. procmond is the only component that ever runs elevated, and it drops privileges after collection setup. +- **Privilege separation**: procmond writes only to the audit ledger; daemoneye-agent reads the audit ledger and reads/writes the event store; daemoneye-cli is read-only. +- **Validated IPC**: Inter-process messages use protobuf with CRC32 framing checks. There are no inbound network listeners; alert delivery is outbound-only. +- **Audit trail**: Events are recorded in a BLAKE3 hash-chained ledger. A Certificate Transparency-style Merkle tree with inclusion proofs is in progress. ## Security Features ### Core Security Controls -- **Memory Safety**: Built in Rust with `unsafe_code = "forbid"` policy -- **Input Validation**: Comprehensive validation with detailed error messages -- **SQL Injection Prevention**: AST validation with sqlparser at rule load time [Implemented]; SQL-based rule execution enforcement [Planned — engine currently uses category-based pattern matching] -- **Credential Management**: Environment variables or OS keychain, never hardcode secrets -- **Attack Surface Minimization**: No network listening, outbound-only connections -- **Audit Trail**: BLAKE3 hash-chained audit ledger [Implemented]; Certificate Transparency-style Merkle tree inclusion proofs \[In Progress — stub returns empty vec in `crypto.rs`\] +- **Memory safety**: Built in Rust with `unsafe_code = "forbid"` at the workspace level. +- **Input validation**: External inputs (CLI args, config files, IPC messages, SQL rules) are validated at boundaries and rejected with actionable errors. +- **SQL injection prevention**: AST validation via sqlparser at rule load time [Implemented]. Execution-time enforcement of the SELECT-only/whitelist policy is [Planned]; the current engine uses category-based pattern matching. +- **Credential handling**: Secrets come from environment variables or the OS keychain. Nothing is hardcoded. +- **Attack surface**: No inbound network listeners. Alert delivery is outbound-only. +- **Audit trail**: BLAKE3 hash-chained audit ledger [Implemented]. Certificate Transparency-style Merkle tree inclusion proofs are [In Progress]; the generator currently returns an empty vec in `crypto.rs`. ### Planned Hardening (Community Tier) -- **Cryptographic Integrity**: Merkle tree with inclusion proofs and periodic checkpoints [In Progress — chain hashing implemented; inclusion proof generation stubbed] -- **Code Signing**: SLSA Level 3 provenance, Cosign signatures [Planned] -- **Sandboxed Execution**: Read-only database connections for detection engine [Planned] -- **Query Whitelist**: Only SELECT statements with approved functions allowed [Implemented at rule load time; not yet enforced at execution time] +- **Cryptographic integrity**: Merkle tree with inclusion proofs and periodic checkpoints. [In Progress]; chain hashing is implemented, inclusion proof generation is stubbed. +- **Code signing**: SLSA Level 3 provenance and Cosign signatures on releases. [Planned] +- **Sandboxed execution**: read-only database connections for the detection engine. [Planned] +- **Query whitelist**: SELECT-only with an approved-function list. [Implemented at rule load time; not yet enforced at execution time] > Fleet-level transport security (mTLS between host agents and upstream aggregators) is provided by commercial tiers, sold separately, not in this repo. @@ -52,62 +51,49 @@ DaemonEye implements a **three-component security architecture** with strict pri ### How to Report -**For security vulnerabilities in DaemonEye, please report them privately to:** +To report a security vulnerability in DaemonEye, contact us privately: -- **Email**: -- **PGP Key**: [Available on our website](https://evilbitlabs.io/security) -- **Subject**: `[SECURITY] DaemonEye Vulnerability Report` +- Email: +- PGP key: [available on our website](https://evilbitlabs.io/security) +- Subject line: `[SECURITY] DaemonEye Vulnerability Report` ### What to Include -Please include the following information in your report: +In your report, please include: -1. **Description**: Clear description of the vulnerability -2. **Impact**: Potential security impact and affected components -3. **Reproduction**: Steps to reproduce the issue (if applicable) -4. **Environment**: OS, architecture, and DaemonEye version -5. **Timeline**: Any disclosure timeline requirements -6. **Contact**: Your preferred contact method for follow-up +1. **Description**: what the vulnerability is and which component(s) are affected. +2. **Impact**: what an attacker could do with it, and what data or capabilities are at risk. +3. **Reproduction**: steps to reproduce, if you have them. +4. **Environment**: OS, architecture, and DaemonEye version (`daemoneye-cli --version`). +5. **Timeline**: any disclosure timeline you need from us. +6. **Contact**: how you would like us to follow up. ### Response Timeline -- **Initial Response**: Within 48 hours of report receipt -- **Status Updates**: Weekly updates during investigation -- **Resolution**: Target resolution within 30 days for critical issues -- **Disclosure**: Coordinated disclosure following resolution +- Initial acknowledgment: within 48 hours of receipt. +- Status updates: weekly while the report is under investigation. +- Resolution target: 30 days for critical issues. +- Disclosure: coordinated with the patch release. ### What to Expect -**If Accepted:** - -- Acknowledgment within 48 hours -- Regular status updates during investigation -- Credit in security advisories (if desired) -- Early access to patches before public release +If we accept the report, you will get credit in the resulting advisory (if you want it) and early access to patches before public release. -**If Declined:** - -- Clear explanation of why the issue doesn't qualify -- Suggestions for alternative reporting channels if applicable -- Option to appeal the decision +If we decline, we will explain why and point you to a more appropriate reporting channel where one exists. ## Security Best Practices -### For Users +### For Operators -- **Keep Updated**: Always run the latest version of DaemonEye -- **Secure Configuration**: Use strong authentication and encryption -- **Monitor Logs**: Regularly review audit logs for anomalies -- **Principle of Least Privilege**: Run components with minimal required permissions -- **Network Security**: Ensure secure communication channels for alert delivery +- Run with the minimum privileges DaemonEye needs. procmond will request elevated privileges at startup if it has to and drop them after collection setup. +- Review the audit ledger periodically; tampering is detectable through the BLAKE3 chain. +- Keep DaemonEye updated. Advisories are published in the channels listed below. ### For Developers -- **Code Review**: All security-related changes require thorough review -- **Testing**: Comprehensive security testing including fuzzing and penetration testing -- **Dependencies**: Regular security audits of dependencies -- **Documentation**: Document security considerations and threat models -- **Training**: Regular security training and awareness +- Security-relevant changes get reviewed before merge. +- CI runs `cargo audit` and `cargo deny check` on every commit, with no allow-listed advisories. New advisories fail the build. +- Security-critical components (input parsers, IPC framing, SQL validation) are covered by unit tests; fuzzing of these components is planned. ## Security Advisories @@ -119,29 +105,23 @@ Security advisories are published at: ## Responsible Disclosure -We follow responsible disclosure practices: - -1. **Private Reporting**: Report vulnerabilities privately first -2. **Reasonable Time**: Allow reasonable time for fixes before public disclosure -3. **Coordinated Release**: Coordinate public disclosure with patch availability -4. **Credit**: Provide appropriate credit to security researchers -5. **No Retaliation**: We will not pursue legal action against good-faith security research +We work under coordinated disclosure: report privately first, give us reasonable time to ship a fix, and we will release the advisory together with the patch. Researchers who report in good faith get credit (if they want it) and will not be threatened with legal action. ## Accepted Risks (Dependencies) -We have **no** outstanding accepted risks. +We have no outstanding accepted risks. ### Advisory Resolution History -**March 2026** — Resolved RUSTSEC-2023-0089 (atomic-polyfill unmaintained) and RUSTSEC-2025-0141 (bincode unmaintained) by disabling default features on the `postcard` dependency (`default-features = false`) and explicitly enabling only the required `alloc` feature. This removed `heapless` and `atomic-polyfill` from the dependency tree entirely. Both advisory ignore entries were removed from deny.toml. +**March 2026.** Resolved RUSTSEC-2023-0089 (atomic-polyfill unmaintained) and RUSTSEC-2025-0141 (bincode unmaintained) by disabling default features on `postcard` (`default-features = false`) and enabling only the required `alloc` feature. This removed `heapless` and `atomic-polyfill` from the dependency tree entirely. Both advisory ignore entries were removed from `deny.toml`. -**January 2025** — Resolved RUSTSEC-2024-0384 (`instant`) and RUSTSEC-2024-0436 (`paste`) by removing the third-party `busrt` broker dependency. With the introduction of the in-house `daemoneye-eventbus` crate, both advisories were eliminated from the workspace. +**January 2025.** Resolved RUSTSEC-2024-0384 (`instant`) and RUSTSEC-2024-0436 (`paste`) by removing the third-party `busrt` broker. The replacement in-house `daemoneye-eventbus` crate eliminated both advisories from the workspace. ### Operational Controls -- CI continues to enforce `cargo audit` and `cargo deny check` with zero allow-listed advisories. -- We maintain a strict posture for all vulnerabilities and unsound advisories and will fail CI on new issues. -- Tracking issues document any future exceptions should they become necessary. +- CI enforces `cargo audit` and `cargo deny check` with no allow-listed advisories. +- New vulnerabilities or unsound advisories fail CI; we do not silently ignore them. +- If we ever need to accept a risk, the rationale, scope, and removal plan get tracked in a public issue. ## Security Contact @@ -153,4 +133,4 @@ For general security questions or concerns: --- -**Last Updated**: March 2026 **Next Review**: March 2027 +Last updated: March 2026. Next review: March 2027. From 8083f537c605d6b3ab8bd99cb6d085148b69b04f Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Thu, 30 Apr 2026 00:50:53 -0400 Subject: [PATCH 10/11] docs: address PR #179 review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolve eight inline review threads from CodeRabbit and Copilot on PR #179: - docs/src/project-overview.md:137 — drop the bare "procfs" claim. procfs was removed from procmond/Cargo.toml in favor of sysinfo; the doc now says "sysinfo (procfs access through the sysinfo abstraction; the workspace does not depend on the procfs crate directly)". - docs/src/introduction.md:14 — drop the "Ed25519-signed events" claim. daemoneye-lib/src/crypto.rs implements BLAKE3 hashing only; Ed25519 is planned, not yet present. Note this explicitly. - .kiro/steering/structure.md:46 — replace the stale six-module list with the actual lib.rs surface: always-on (config, crypto, integrity, ipc, models, proto, storage, telemetry) plus the feature-gated modules (alerting, collection, detection, kernel, network) with their Cargo feature names. Mark kernel/network as commercial-tier-backed. - .kiro/steering/tech.md:132 and docs/src/introduction.md:18 — hyphenate "commercial-tier" when used as a compound adjective before a noun, matching the rest of the boundary statements. - README.md:167 (was :169) — add a SECURITY.md pointer under the RPC services bullet covering transport security, authn/authz, and fleet-level deployment responsibilities. - README.md:172 — replace the broken `just docs-install` reference with the actual workflow: `mise install` (which provisions mdbook + plugins per mise.toml) then `mdbook build docs`. Refs: #179 Signed-off-by: UncleSp1d3r --- .kiro/steering/structure.md | 3 ++- .kiro/steering/tech.md | 2 +- README.md | 4 ++-- docs/src/introduction.md | 4 ++-- docs/src/project-overview.md | 2 +- 5 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.kiro/steering/structure.md b/.kiro/steering/structure.md index 52fdcbf4..294d6422 100644 --- a/.kiro/steering/structure.md +++ b/.kiro/steering/structure.md @@ -43,7 +43,8 @@ DaemonEye/ ### daemoneye-lib/ (Shared Core) - **Purpose**: Common functionality shared across all components -- **Modules**: config, models, storage, detection, alerting, crypto, telemetry +- **Always-on modules**: config, crypto, integrity, ipc, models, proto, storage, telemetry +- **Feature-gated modules**: alerting (`alerting`), collection (`process-collection`), detection (`detection-engine`), kernel (`kernel-monitoring`), network (`network-correlation`); the kernel and network modules back commercial-tier collectors and are gated off by default in this repo - **Security**: Trait-based abstractions with security boundaries ### collector-core/ (Collector SDK) diff --git a/.kiro/steering/tech.md b/.kiro/steering/tech.md index 19abd261..9c16810c 100644 --- a/.kiro/steering/tech.md +++ b/.kiro/steering/tech.md @@ -129,7 +129,7 @@ just run-daemoneye-agent --config /path # Run orchestrator agent - **Phase 2**: Platform-specific enhancements (Planned) - **Fallback**: Graceful degradation when enhanced features unavailable -> Kernel-level monitoring (eBPF / ETW / EndpointSecurity) is provided by commercial tier collectors that are sold separately, not in this repo. +> Kernel-level monitoring (eBPF / ETW / EndpointSecurity) is provided by commercial-tier collectors that are sold separately, not in this repo. ### Privilege Management diff --git a/README.md b/README.md index 62f42daa..25065512 100644 --- a/README.md +++ b/README.md @@ -164,12 +164,12 @@ Additional OS/environment variables may be referenced in tests for compatibility - **Windows**: IPC over named pipes via the `interprocess` crate, using protobuf messages. - **Event bus**: `daemoneye-eventbus` is local-only pub/sub between collectors and the agent on the same host. Topics are hierarchical and messages carry correlation metadata. - **Embedded broker**: `daemoneye-agent` runs the EventBus broker in-process. Workflow tracking and forensic correlation are built on top of it. -- **RPC services**: Collector lifecycle (start, stop, restart, health checks) is exposed over RPC on the bus with request timeouts and correlation IDs. +- **RPC services**: Collector lifecycle (start, stop, restart, health checks) is exposed over RPC on the bus with request timeouts and correlation IDs. The bus is local-only on a single host; for transport security, authn/authz, and fleet-level deployment responsibilities, see [SECURITY.md](SECURITY.md). - **Multi-collector coordination**: Tasks are distributed by topic and routed by collector capability; results are aggregated across collector types. ## Documentation -- Docs sources live under ./docs (mdBook). Build locally with `just docs-install` then `mdbook build docs`. +- Docs sources live under ./docs (mdBook). Build locally with `mise install` (which installs `mdbook` and its plugins per `mise.toml`) then `mdbook build docs`. ## License diff --git a/docs/src/introduction.md b/docs/src/introduction.md index dd42c743..09552314 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -11,11 +11,11 @@ DaemonEye is an agent-centric system monitoring tool designed for cybersecurity - **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; Ed25519-signed events +- **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 tiers (fleet management, GUI, federation, kernel-level collectors) extend this foundation and are sold separately through evilbitlabs.io; they are not in this repo. +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 diff --git a/docs/src/project-overview.md b/docs/src/project-overview.md index 35bdbbbf..f5e05f24 100644 --- a/docs/src/project-overview.md +++ b/docs/src/project-overview.md @@ -134,7 +134,7 @@ This repository ships the agent-side Community tier. It is appropriate for indiv #### Cross-Platform Support -- **Linux**: Native process enumeration via `sysinfo` and procfs +- **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 From f08b4c73891639103ecba0a059cb4d4f5c239687 Mon Sep 17 00:00:00 2001 From: UncleSp1d3r Date: Thu, 30 Apr 2026 21:53:54 -0400 Subject: [PATCH 11/11] docs: address PR #179 review feedback (round 2) Two new CodeRabbit threads after the previous push: SECURITY.md:18-22 (individual, Major) The Security Architecture inventory listed three binaries plus daemoneye-lib but omitted collector-core and daemoneye-eventbus, under-documenting the in-repo trust boundaries and IPC/broker attack surface. Added entries for both supporting crates with brief privilege/transport descriptions; reworded the lead-in to say "three supporting library crates" instead of the singular "a shared library". .kiro/steering/structure.md (cluster, holistic sweep) The reviewer flagged the line-5 "three-component security architecture" claim as inconsistent with the six-crate workspace listed below it. Cross-invocation gate fired (this is the second round of factual-accuracy feedback on this same file in this PR), so this commit reads the file holistically and fixes everything stale that I found while in there: - Line 5: "three-component" headline replaced with "privilege-separated runtime architecture within a six-crate workspace" matching the actual layout. - Line 65: MSRV claim updated from "1.85+" to "1.95+", matching Cargo.toml's workspace `rust-version`. - Line 70: malformed commit-instructions.md link (`#\[[file:.github/...]\]`) replaced with a real relative link. - Lines 74-82: stale Module Organization pseudo-code (which hard-coded a six-module list missing integrity, ipc, proto, telemetry, and the feature-gated modules, and had a comment collision on the `storage` line) replaced with a pointer to the authoritative daemoneye-lib section earlier in the doc. - Lines 121-123, 188-189: "DaemonEye_*" env-var prefix and "/etc/DaemonEye/" / "~/.config/DaemonEye/" config paths corrected to the actual lowercase forms used by the codebase (DAEMONEYE_AGENT_*, DAEMONEYE_CLI_*, PROCMOND_*, and lowercase `daemoneye` directories). - Line 194: "project_spec/" replaced with "spec/", which is the directory that actually exists in the workspace. - Line 196: "Operator Guide: User-facing documentation in `docs/`" rewritten to describe the mdBook docs layout, since the user-facing operator guide content was removed earlier in this PR. Refs: #179 Signed-off-by: UncleSp1d3r --- .kiro/steering/structure.md | 33 +++++++++++++-------------------- SECURITY.md | 4 +++- 2 files changed, 16 insertions(+), 21 deletions(-) diff --git a/.kiro/steering/structure.md b/.kiro/steering/structure.md index 294d6422..e3a84543 100644 --- a/.kiro/steering/structure.md +++ b/.kiro/steering/structure.md @@ -2,7 +2,7 @@ ## Workspace Organization -DaemonEye follows a **three-component security architecture** with strict privilege separation: +DaemonEye uses a **privilege-separated runtime architecture** within a six-crate workspace (three binaries plus three supporting library crates): ```text DaemonEye/ @@ -62,24 +62,16 @@ DaemonEye/ ### Workspace Configuration -- **Edition**: Rust 2024 (MSRV: 1.85+) +- **Edition**: Rust 2024 (MSRV: 1.95+, per `Cargo.toml`'s workspace `rust-version`) - **Resolver**: Version 3 for enhanced dependency resolution - **Lints**: `unsafe_code = "forbid"`, `warnings = "deny"` - **Quality**: Zero-warnings policy enforced by CI - **AI Restrictions**: Never remove clippy restrictions or allow linters marked as `deny` without explicit permission -- **Commit Message Style**: Always follow the commit message style in #\[[file:.github/commit-instructions.md]\]. +- **Commit Message Style**: Always follow the commit message style in [`.github/commit-instructions.md`](../../.github/commit-instructions.md). ### Module Organization -```rust,ignore -// Library structure pattern -pub mod alerting; // Multi-channel alert delivery -pub mod config; // Configuration management -pub mod crypto; -pub mod detection; // SQL-based detection engine -pub mod models; // Core data structures -pub mod storage; // Database abstractions // Cryptographic audit functions -``` +For the actual `daemoneye-lib` module surface (always-on vs feature-gated), see the [daemoneye-lib/](#daemoneye-lib-shared-core) section above. New modules should follow the same pattern: always-on for cross-component utilities, feature-gated when the module pulls in optional subsystems (alerting sinks, kernel integrations, network correlation). ### Error Handling Pattern @@ -118,9 +110,9 @@ All development tasks use the `just` command runner: Hierarchical configuration with clear precedence: 1. Command-line flags (highest precedence) -2. Environment variables (`DaemonEye_*`) -3. User configuration files (`~/.config/DaemonEye/`) -4. System configuration files (`/etc/DaemonEye/`) +2. Environment variables, component-namespaced (`PROCMOND_*`, `DAEMONEYE_AGENT_*`, `DAEMONEYE_CLI_*`) +3. User configuration files (`~/.config/daemoneye/`) +4. System configuration files (`/etc/daemoneye/`) 5. Embedded defaults (lowest precedence) ## Database Schema Design @@ -185,12 +177,13 @@ src/ ### Configuration Files -- **System**: `/etc/DaemonEye/config.yaml` -- **User**: `~/.config/DaemonEye/config.yaml` +- **System**: `/etc/daemoneye/config.yaml` +- **User**: `~/.config/daemoneye/config.yaml` - **Service**: Platform-specific service definitions in `scripts/service/` ### Documentation Structure -- **Specifications**: `project_spec/` directory with comprehensive docs -- **API Documentation**: Generated from code with `cargo doc` -- **Operator Guide**: User-facing documentation in `docs/` +- **Specifications and design notes**: `spec/` directory +- **Steering documents**: `.kiro/steering/` (this file lives here) +- **API documentation**: Generated from code with `cargo doc` +- **mdBook content**: `docs/` holds the sources; build them with `mise install` then `mdbook build docs` diff --git a/SECURITY.md b/SECURITY.md index c31b48fe..4cbf76a8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -13,12 +13,14 @@ DaemonEye is in pre-1.0 development, so security updates target the latest 0.1.x ## Security Architecture -DaemonEye is split into three binaries with strict privilege separation, plus a shared library: +DaemonEye is split into three binaries with strict privilege separation, plus three supporting library crates. The full workspace inventory: - **procmond**: privileged process collector. Runs elevated only as long as it needs to. - **daemoneye-agent**: user-space orchestrator for detection and alert delivery. - **daemoneye-cli**: read-only operator interface. - **daemoneye-lib**: shared library (config, models, storage, detection, crypto). No direct privileges of its own. +- **collector-core**: collector SDK consumed by procmond (`EventSource` trait, runtime, capability negotiation, IPC contracts). Runs in the calling process; no privileges of its own. +- **daemoneye-eventbus**: embedded pub/sub + RPC broker hosted inside daemoneye-agent for local cross-process collector coordination. Local-only transport (Unix domain sockets on Linux/macOS, named pipes on Windows); no inbound network listeners. ### Security Principles